API reference · Using the APIAuthentication
Authentication
Send a team API token as a bearer token. What full and read tokens may do, project-limited tokens, and the few things no token can do.
Every request carries an API token in the Authorization header:
Authorization: Bearer orb_live_…A request without one, or with a token that is wrong, revoked or expired, answers 401.
Make a token
API tokens are made in the dashboard, under Team › Settings › API tokens, by the team's owners and admins. Choose:
- Access:
full(deploy, change settings and domains) orread(see projects, deployments and logs). - Project: all of the team's projects, or one.
- Expires: after 30, 90 or 365 days, or never.
The token (orb_live_ and 32 characters) is shown once, when it is made: Orbits keeps only a hash of it. Store it in your CI's secrets or a password manager. A team can have up to 50 active tokens. See API tokens for the guide.
The CLI and the SDKs read the token from ORBITS_TOKEN; the examples in this reference do too.
What a token acts as
A token belongs to one team and acts as the person who made it. It can do what that person's role allows in that team, within its own access, and no more. It stops working when that person leaves the team, and while the team requires two-factor authentication and the person has it off. The team's rules on sign-in methods and session length apply to sessions, not tokens.
GET /v1/me shows who the token acts as, and the one team (and project, for a project-limited token) it reaches.
Full and read tokens
read | full | |
|---|---|---|
GET and HEAD requests | Yes | Yes |
| Anything else (create, change, delete, deploy) | No: 403 "This API token is read-only" | Yes |
| Environment variable values | Never (revealing and pulling are POSTs) | Yes |
Each operation in the reference says which it needs: Read or full token, or Full token.
Project-limited tokens
A token limited to one project reaches only that project's routes (/v1/teams/{team}/projects/{project}/… for that project), and /v1/me and the team list show it only that team and project.
What no token can do
Some things are only ever done by a signed-in person in the dashboard. A token that tries answers 403 ("API tokens can't use this endpoint" or "API tokens can't manage integrations"):
- signing in, and the account routes (
/v1/auth/…,/v1/me/…), such as your profile, email and two-factor settings; - creating teams, accepting or declining invites, and deleting the team;
- making, listing or revoking API tokens;
- managing members and invites;
- the team's security rules: required two-factor, allowed sign-in methods, session length, and who can invite;
- moving a project to another team;
- connecting, changing or disconnecting Git and notification integrations (listing them,
GET /v1/teams/{team}/integrations, is fine); - paying for, cancelling or resuming a plan (reading billing is fine).
Outside a team, a token may call GET /v1/me, GET /v1/teams, GET /v1/templates and GET /v1/operations/{operation}.