Team and accountAPI tokens
API tokens
Tokens let the CLI, CI and your own scripts act on a team without a browser. Make one under Team › Settings › API tokens, choose full or read-only access and an expiry, limit it to one project if you like, and copy the secret, which is shown once.
What a token is
An API token is a credential for the CLI, CI pipelines, the SDKs and your own scripts. It looks like this:
orb_live_8hTq2vXk9mPz4RwLc7NdYs1bGfJe6aUoorb_live_ and 32 more characters. A token:
- belongs to one team, and reaches only that team;
- acts as the person who made it, with their role in the team;
- is a CLI or CI credential, not a login: it can't reach your account, sign-in or the team's most sensitive settings (see what a token can't do).
Treat tokens like passwords. Tokens act as you in the CLI and in CI.
Create a token
Owners and admins manage the team's tokens, signed in to the web app.
- Go to Team › Settings › API tokens and press Create token.
- Name it after where it will run, like
github-actionsorada-laptop: 1 to 40 characters, letters, numbers, dots, dashes and underscores, starting with a letter or number. Names are unique among the team's active tokens. - Pick its Access:
- Full access: deploy, change settings and domains.
- Read only: see projects, deployments and logs.
- Pick its Projects: All projects, or one project. A token limited to a project reaches only that project: listing the team's projects or deployments shows just that one, and other team-wide pages (domains, usage, activity, settings) refuse it.
- Pick when it Expires: In 30 days, In 90 days, In a year or Never.
- Press Create token, then Copy token.
A team can have at most 50 active tokens. Creating and revoking a token are both lines in the team's activity feed.
The token list
The API tokens card lists every token that isn't revoked, newest first:
| Column | |
|---|---|
| Name | The name you gave it |
| Hint | orb_live_••••3f9a: the last four characters, so you can tell tokens apart |
| Access | Full access or Read only, and the project it's limited to, if any |
| Created | When, and by whom: the person it acts as |
| Last used | When it was last used (to the minute) and by which client, such as orbits-cli/0.4.1. "It hasn't been used yet" until its first request |
| Expires | The date, or "It doesn't expire" |
An expired token stays in the list, marked with its expiry, until someone revokes it. It answers 401 from the moment it expires.
Revoke a token
Press Revoke token on its row. It stops working at once (its next request is a 401) and leaves the list. Revoke a token as soon as it might have leaked, then make a new one.
Full and read-only
| Full access | Read only | |
|---|---|---|
| Methods | Any | GET and HEAD only |
| Read projects, deployments, logs, usage, activity | Yes | Yes |
| Deploy, promote, roll back, change settings and domains | Yes | No |
Read environment variable values (reveal, orbits env pull) | Yes | No |
A read-only token can see which variables exist, but never their values: revealing and pulling values are writes. A read-only token answers 403 "This API token is read-only" to anything else.
What a token can't do
Some things are never a token's, whatever its access. They need a person signed in to the web app:
- signing in, and anything about your account (
/v1/auth/...,/v1/me/...); - creating teams and accepting invites;
- managing API tokens;
- deleting the team;
- the team's security rules: two-factor, sign-in methods, session length, who can invite;
- members and invites;
- moving a project to another team;
- Git and notification integrations (listing them is fine);
- paying for, cancelling or resuming Pro (tokens can read the billing state, never change it).
These answer 403 with a sentence that says so, such as "API tokens can't manage integrations".
Outside its team, a token can only call GET /v1/me, GET /v1/teams, GET /v1/templates and GET /v1/operations/{id}, and those show it only its own team (and project, if it's limited to one).
When a token stops working
- It's revoked, or it expires.
401. - Its maker leaves the team, or is removed. The token acts as that person, so it stops at once. It stays dead even if they rejoin: tokens made before someone's current membership began never work again.
- The team requires two-factor and its maker has it off. The team's two-factor rule applies to the person a token acts as, so their tokens are refused until they turn two-factor on.
The team's sign-in method and session-length rules are about browser sessions, so they don't affect tokens.
Use a token
Send it as a bearer token:
$ curl -s https://api.theorbits.app/v1/teams/acme/projects \ -H "Authorization: Bearer $ORBITS_TOKEN"See API › Authentication.
With the CLI
On a machine without a browser, pass the token on standard input:
$ orbits login --with-token < token.txt$ orbits whoamiIn scripts and CI, set ORBITS_TOKEN instead. It is used in place of any stored sign-in, and nothing is written to disk:
$ export ORBITS_TOKEN=orb_live_…$ orbits --project storefront deploy ./dist --no-logsOn your own computer, orbits login signs you in through the browser instead, and makes a token for the CLI for you.
In GitHub Actions
Save the token as a repository secret named ORBITS_TOKEN, then:
- name: Deploy to Orbits
env:
ORBITS_TOKEN: ${{ secrets.ORBITS_TOKEN }}
run: orbits --project storefront deploy ./dist --no-logsGive CI the narrowest token that works: limited to the one project, read-only if it only reads, and with an expiry.
Rate limits
Each token has its own budget, apart from its maker's: 300 requests a minute, in bursts of up to 100. The team's budget of 6,000 a minute is shared by its members and its tokens together. Over a limit the API answers 429 with Retry-After. See rate limits.
From the API
Owners and admins, signed in (a token can't manage tokens):
| Call | |
|---|---|
GET /v1/teams/{team}/tokens | The list |
POST /v1/teams/{team}/tokens | Create one. Body: name, access (full or read), expires (30, 90, 365 or never) and optionally project. The answer's secret is the only time you see it |
DELETE /v1/teams/{team}/tokens/{token} | Revoke one |
Creating a token ignores Idempotency-Key: each call makes a new token, so a retry never hands back an old secret. See API › Teams.