Scopes
What a scope is, how a credential gets its scopes, and the scopes of each product.
A scope is <product>:<resource>.<verb>, chosen when a key is created and granted by a trust rule on an exchange. Each endpoint's reference names the scope it needs; in Ciresk CI, the CLI, MCP tools and API check the same scope for the same capability. A request without the scope is 403 insufficient_scope with required_scope in the problem.
Ciresk CI scopes
Every Ciresk CI scope is ci:<resource>.<verb>; the Ciresk CI API reference names the one each endpoint needs.
| Scope | Allows |
|---|---|
ci:jobs.read | Reading jobs, summaries, logs, tests, artifacts and tasks, and waiting for a job |
ci:jobs.run | Submitting jobs |
ci:jobs.run_full | full: true on a job; the policy must allow it too |
ci:jobs.cancel | Cancelling jobs |
ci:approvals.approve | Approving or rejecting a job's approval gate, as a person signed in within the last 10 minutes; never granted to a key or an agent |
ci:repos.read, ci:repos.write | Reading and registering repositories |
ci:repos.admin | Deleting repositories |
ci:blobs.read, ci:blobs.write | Tree sync: declaring, uploading and downloading blobs |
ci:events.read, ci:events.write | Following a job's events and listing webhooks; creating and deleting webhooks |
ci:queue.read | The queue depth |
ci:workers.read, ci:workers.admin | Listing workers; enrolment secrets and deregistering workers |
ci:workspaces.read, ci:workspaces.admin | Listing and evicting warm workspaces |
ci:cache.admin | Evicting cache entries |
ci:policy.read, ci:policy.write | The effective policy and overrides |
ci:budget.read, ci:audit.read | Budgets and the audit log |
ci:workers.lease, ci:workers.heartbeat, ci:workers.report, ci:workers.cache | The worker protocol: leases, heartbeats, reports and cache entries; only worker tokens hold them |
How a credential gets scopes
| Credential | Scopes |
|---|---|
| API key | Chosen when the key is created on platform.ciresk.com; a key for an agent sandbox usually has ci:jobs.run, ci:jobs.read, ci:repos.read, ci:blobs.read and ci:blobs.write. |
| Exchanged token | What requested_scopes asks for, which must be within what your organization's trust rule grants the repository and ref (a scope outside it is 403 insufficient_scope); with no requested_scopes, the whole grant. The GitHub Action asks for the five above; ci:repos.write is left out, so the repository must be registered before the first CI run. |
| Person token | Everything the person's role allows. |
| Worker token | ci:workers.lease, ci:workers.heartbeat, ci:workers.report, ci:workers.cache, ci:workers.read and ci:blobs.read, for one worker id. |
Scopes say what a credential may call; a product's policy says how the call runs. In Ciresk CI a key with ci:jobs.run_full still gets 403 policy_denied for a full build when the policy's allow_full_build is off. See Workers and trust.
Other products
Kepler, Scribe and Context use the same <product>:<resource>.<verb> form; their scopes are not published here yet. Trace and Ciresk Agent take no API keys today.