Skip to content
Hayonix

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 leave org_id out; GET /v1/caller returns 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:

HTTP
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:

ScopeAllows
inference:invokeCalling models through the inference API
model:readListing 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:readThe 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.

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:

HTTP
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.