Concepts

Scopes

A scope names what a credential may do in one service. The gateway checks the operation's scope before the request reaches the service, and refuses with 403 SCOPE_MISSING and the scope it needed.

The rule

For most services the scope is <service>:read for GET and <service>:write for everything else.

• Write includes read. A key with hives:write can call every hives:read operation.
• flocks:admin includes flocks:read and flocks:write.
• auto:* includes auto:read and auto:write.
• Lanes treats its read-only POSTs (retrieve, snapshots, cache lookup and tenant export) as lanes:read.
• Gears uses one scope per resource and verb: gears.workflows.read, gears.workflows.write, gears.runs.read, gears.runs.write, gears.signals.write, and gears.operations.read (or gears.audit.read) for operational records.
• Gears also accepts the coarse gears:read (for reads), gears:write and gears.* (for everything).
• Beacons device enrollment (device-challenges, device-enrollments) needs beacons:device:enroll.
• Foundry inference and generation reads need foundry:gateway:invoke, a scope delegated to a signed-in session; files, fine-tuning, batches, activity and analytics need admin; provider keys and credential policies need iam:read or iam:write; the model catalog and registry need no credential.
• Minds, and Foundry's keys, billing and request logs, are authorized by the service itself for the signed-in person; the gateway publishes no scope for them.

Each operation in the API reference shows its scope next to its endpoint.

When a scope is missing

{
  "error": {
    "type": "forbidden",
    "code": "SCOPE_MISSING",
    "message": "The credential lacks the scope named in required_scope.",
    "request_id": "02f92096-3625-4ff2-a6ff-87df16d75e0f",
    "docs_url": "https://os.one.ml/api/v1/errors#SCOPE_MISSING",
    "required_scope": "hives:write"
  }
}

Create a key with required_scope added, or ask an organization owner or admin to. A key's scopes are fixed when it is created.

Choosing scopes

• Give each key the fewest scopes it needs: a deploy job needs hives:write; a dashboard needs only hives:read.
• A key can carry only scopes your own role holds.
• genesis whoami and GET /v1/whoami list a credential's scopes.

Every scope by service

One Superintelligence, Inc. · Built from Genesis 0.1.12 and the live gateway on 2026-10-20. Support