API authentication

Orbit has several kinds of credentials. Pick the one that matches who or what is calling.

Caller	Credential	Used for
A browser	Session cookie orbit_session	The web application
A script or tool acting as a person	Personal API token opt_...	The Orbit API
An integration	Service-account API token	The Orbit API
A telemetry sender	Pulse ingest key	Sending telemetry only
A Git client or CI job	Forge project access token	Git and the Forge API
A Lumen agent	Agent session oas_...	Read-only access issued by Orbit

Session cookie

Signing in sets an orbit_session cookie that is HttpOnly and SameSite=Lax. Send browser requests with credentials. Writes check the request’s Origin against the site, and a rejected origin answers 403. Other Orbit services use the same session: Pulse, Folio, Forge and Lumen resolve it on every request and check your current project role.

Personal API tokens

Send the token as a bearer header:

curl -H "Authorization: Bearer opt_..." https://acme.orbit.inortix.com/api/v1/auth/me

• The token acts as its owner and never has site administration, so administrator-only routes answer 403 token_not_allowed.
• A read token can only GET (403 token_read_only otherwise).
• A project-limited token reads only the routes of those projects.
• No token can manage tokens or list them (403 session_required). Use a signed-in session for that.
• Create tokens from your profile. See Service accounts and API tokens for lifetimes and limits.

Personal and service-account tokens work only on the Orbit API. They do not authenticate Forge, which uses project access tokens, or Pulse, where reading needs a signed-in session.

Service-account tokens

A service account has its own tokens, issued by its owners and site administrators, with the same format and rules. Suspending the account or losing its last owner stops every token on the next request with 403 service_account_inactive.

Errors

Status	Code	Meaning
401	invalid_token	The token is not recognised
401	token_revoked	The token was revoked
401	token_expired	The token expired
403	token_read_only	A read token tried to write
403	token_not_allowed	The route needs site administration, which no token has
403	session_required	The route needs a signed-in session, not a token
403	service_account_inactive	The service account is suspended or has no owner
403	product_access_required	The person may not open that product
429	rate_limited	Too many requests. Read Retry-After.

Rate limits

Each token has 600 requests a minute. Responses carry X-RateLimit-Limit and X-RateLimit-Remaining. A request over the limit answers 429 with a Retry-After header. Sign-in is throttled separately: ten failed attempts for one address in 15 minutes.

Pulse ingest keys

A project ingest key authenticates telemetry senders. Send it as X-Pulse-Key: <key> or Authorization: Bearer <key>. The key decides the project, and anything in the payload that names a project is ignored. Ingest keys are for sending telemetry only. People and services acting for a person use the session cookie, and Pulse checks the person’s current project role: viewers and members read, project administrators manage keys and settings.

Forge project access tokens

Forge issues hashed project access tokens for Git over HTTPS and the Forge API. Scopes are read_repository, write_repository, read_api and api, with a lifetime of 1 to 365 days. A token works only in its project, read_api is read-only, and no token can administer tokens, secrets, approvals or the instance. SSH keys give Git over SSH.

Lumen agent sessions

Agent sessions (oas_...) are issued by Orbit to Lumen when a person has granted an agent access to some of their projects. They are sent as Authorization: Bearer oas_..., last ten minutes, and are read-only: only GET on a short list of routes, limited to the grant’s projects. You do not create them yourself.

Status

All credentials above are built, except that the Lumen MCP server for coding agents is in development.