Authentication & scopes

Get a key

In your organisation: Settings → Platform API → Create key (Pro plan). The sc_… secret is shown exactly once — store it like a password. Send it on every request:

Authorization: Bearer sc_your_key

Pick a scope

Scopes are ranked — each includes everything below it. Start with read and only step up when an endpoint tells you to.

• read — GET anything your org can see.
• score — also POST score events and start divisions.
• manage — the full surface: create, generate, moderate.

Each operation in the reference declares its requirement as x-required-scope. Billing, org membership and key management are never reachable with a key, whatever the scope.

Pin a key to one competition

When a scoreboard vendor only needs one event, create the key with a competition pin. It authenticates normally but 403s anywhere outside that competition — including org-wide collection endpoints.

Errors you will meet

{ "ok": false,
  "error": { "code": "FORBIDDEN", "message": "This key is limited to 'read' — this endpoint needs the 'manage' scope. Create a key with the right scope in org settings." },
  "requestId": "…" }

• 401 UNAUTHENTICATED — bad or revoked key.
• 403 FORBIDDEN — scope too low, pinned elsewhere, or a key can’t use that endpoint at all.
• 402 PAYMENT_REQUIRED — the org’s plan doesn’t include the feature; error.feature_key says which.
• 429 RATE_LIMITED — over the per-key budget; check X-RateLimit-Reset and retry after it.