Concepts
Projects and API keys
How organizations, projects and keys relate, what a key may be allowed to do, and when a request needs X-Project-Id.
Organizations and projects
An organization holds the members, the credit balance, billing settings and quotas. It contains one or more projects, and every resource you create (pods, volumes, secrets, endpoints, files, fine-tunes, batches) lives in exactly one project. IDs have a type prefix (pod_, vol_, sep_…) and are unique across the platform; an ID from another project is answered with 404, the same as an ID that never existed.
Routes come in two shapes:
- Project-level routes are short:
/v1/pods,/v1/files/{file_id}. They act in the project of the caller. - Organization-level routes carry the org in the path:
/v1/orgs/{org_id}/billing/balance. The SDKs fill in your key's org when you leaveorg_idout;GET /v1/callerreturns it.
API keys
A key belongs to one project and acts only in it: requests made with a key never name a project. Send it as a bearer token:
Authorization: Bearer sk_…A key carries scopes: actions written resource:verb (file:create, inference:invoke) or resource:* for every verb on a resource. A key can hold at most what the member who created it may do, and only actions on the project's own resources plus a few organization reads:
| Scope | Allows |
|---|---|
inference:invoke | Calling models through the inference API |
model:read | Listing and reading models |
workload:* | Pods |
volume:*, template:* | Volumes and pod templates |
serverless_endpoint:*, serverless_job:* | Serverless endpoints and their jobs |
model_reference:* | Model references (models cached on hosts and mounted into workloads) |
webhook:* | Webhook destinations and delivery logs (webhook:read reads serverless completion deliveries too); receiving organization events also needs billing:read |
dedicated_endpoint:* | Dedicated endpoints |
file:*, fine_tune_job:*, batch:*, evaluation:* | Files, fine-tuning, batches and evaluations |
sandbox:* | Code sandboxes: create, run code, move files, extend and end |
cluster:* | Clusters: create, read, rename and delete |
secret:*, ssh_key:*, registry_credential:* | Project secrets, SSH keys and registry credentials |
billing:read, usage:read, project:read | The balance, usage and cost reports, the project |
A key can never hold api_key scopes, so a leaked key cannot create more keys or keep itself alive: create, rotate and revoke keys in the console. Member, invitation and organization settings, top-ups and payment methods are also console-only. A key may have an expiry date; an expired or revoked key gets 401.
Requests with a key that lacks a scope get 403 with type permission_error.
Keep keys secret
The secret is shown once, when the key is created; the platform keeps only a keyed hash of it and cannot show it again. Put it in a secret manager or an environment variable, never in source code or in a browser.
Console sessions and X-Project-Id
The console calls the same API with a signed-in session instead of a key. A session is not tied to a project, so project-level requests made with a session must send the project explicitly:
X-Project-Id: prj_…The server never remembers an "active" project between requests. With an API key the header is not needed: the key already names its project. A few operations accept only a session; the API reference marks them Console session.