{"id":20502,"plugin_id":"plugins_6aa4f7db79848191a81e4048990545ef","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:16:17.430Z","digest":"6cf091ddea1971275df9496d5fc3b5c1ad911e3a0b92e7ba21431dfd03eccae0","against":null,"payload":{"description":"Authenticate to Sugra over HTTPS and MCP and stay inside the daily quota. Use when setting up a client or when a call returns 401, 403, missing_api_key, missing_bearer_token, or 429.","included_files":[{"relative_path":"agents/openai.yaml","size_in_bytes":221}],"name":"auth-and-quota","skill_md_contents":"---\nname: auth-and-quota\ndescription: Authenticate to Sugra over HTTPS and MCP and stay inside the daily quota. Use when setting up a client or when a call returns 401, 403, missing_api_key, missing_bearer_token, or 429.\nlicense: MIT\n---\n\n# Auth and quota\n\nOne key. Two header shapes. Volume gating only: every plan sees every endpoint. Plans and errors on https://docs.sugra.ai (search Authentication, Rate limits).\n\nIssue a key at https://app.sugra.ai/settings/billing. Prefix `sugra_...`. Do not log it.\n\n| Plan | Requests / day |\n|---|---|\n| Free | 50 |\n| Dev | 5,000 |\n| Pro | 50,000 |\n\nSome bulk endpoints cost more than 1 request. HTTP reports `X-RateLimit-Cost`. MCP `describe_endpoint` `agent_hints.bulk_cost` warns before the call.\n\n## HTTPS API\n\n```\nx-api-key: sugra_...\n```\n\nNot `Authorization: Bearer` on `https://sugra.ai`.\n\nEvery data response also carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (UTC), `X-RateLimit-Cost`.\n\n## MCP\n\n| Transport | Client auth | Process env |\n|---|---|---|\n| Hosted `https://mcp.sugra.ai/mcp` | `Authorization: Bearer` (raw key or OAuth JWT) | n/a |\n| Local stdio | none on the wire | `SUGRA_API_KEY` in the server process |\n| Self-hosted HTTP | client Bearer; process `SUGRA_API_KEY` is only a downstream fallback | |\n\nOAuth JWT: audience `https://app.sugra.ai/mcp` on both MCP hosts, scope `sugra:read`. Hosted discovery is public. `tools/call` and `resources/read` return 401 `missing_bearer_token` without Bearer.\n\nStdio catalog tools (`search_endpoints`, `describe_endpoint`, `list_toolsets`, `list_sources`) work without a key. `call_endpoint`, `fetch_data`, and entity tools return `missing_api_key` until `SUGRA_API_KEY` is set.\n\nMCP tool JSON does not forward `X-RateLimit-*`. On 429 wait for `retry_after` (seconds). Downstream MCP still calls the API with `x-api-key`.\n\n## Errors\n\n| Signal | Meaning | What to do |\n|---|---|---|\n| HTTP 401 / MCP `missing_api_key` / `missing_bearer_token` | missing or invalid credential | stop. Do not retry the same call. |\n| HTTP 403 | key cannot use this route | stop. |\n| HTTP 429 / MCP 429 | quota exhausted | wait until `X-RateLimit-Reset` or `retry_after`. |\n| HTTP 5xx / MCP `upstream_*` | platform or upstream fault | retry once with backoff. Then report. |\n\nDo not retry 4xx except 429 after the reset.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}