Docs

Home All sections Swagger

Scopes and permissions

What every scope grants, and how to pick a safe set for each key.

Last updated June 3, 2026

A scope is a permission attached to an API key. When you call an endpoint, the server checks that your key has every scope that endpoint needs. A request without the right scope fails with 403 scope_required.

Using the Python SDK?

The SDK uses the same scopes the REST API uses. A 403 from the SDK surfaces as AuthenticationError with the missing-scope message.

The full list

Scope What it grants
submissions:read List submissions, fetch a single submission.
submissions:write Create, cancel, and modify submissions.
results:read List results, fetch a single result, download files.
results:write Update result metadata (rename, mark as shared).
code-uploads:read List the code blobs attached to your submissions.
code-uploads:write Upload new code blobs to use in submissions.
webhooks:read List webhooks and their delivery history.
webhooks:write Create, update, and delete webhooks.

Picking a safe set

The rule of thumb is: give the key the smallest set of scopes that lets your code work. A key on a researcher's laptop that only reads results does not need write scopes. A key on a CI server that submits new runs needs submissions:write but probably not webhooks:write.

If you are unsure, start with the read-only scopes and add write scopes when something fails with a 403.

Examples

A keys for a notebook that pulls history of completed runs:

  • submissions:read
  • results:read

A key for a bot that submits jobs:

  • submissions:write
  • submissions:read
  • results:read

A key that fully manages your account from automation:

  • All eight scopes. Use only on a trusted CI server with a short expiry date.

Changing scopes later

You can edit the scopes on an existing key without rotating. See Editing the scopes on an existing key.

Thanks for the feedback!