OrbitsDocs
esc
    Open Orbits
    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:

    text
    orb_live_8hTq2vXk9mPz4RwLc7NdYs1bGfJe6aUo

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

    1. Go to Team › Settings › API tokens and press Create token.
    2. Name it after where it will run, like github-actions or ada-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.
    3. Pick its Access:
      • Full access: deploy, change settings and domains.
      • Read only: see projects, deployments and logs.
    4. 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.
    5. Pick when it Expires: In 30 days, In 90 days, In a year or Never.
    6. 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
    NameThe name you gave it
    Hintorb_live_••••3f9a: the last four characters, so you can tell tokens apart
    AccessFull access or Read only, and the project it's limited to, if any
    CreatedWhen, and by whom: the person it acts as
    Last usedWhen 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
    ExpiresThe 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 accessRead only
    MethodsAnyGET and HEAD only
    Read projects, deployments, logs, usage, activityYesYes
    Deploy, promote, roll back, change settings and domainsYesNo
    Read environment variable values (reveal, orbits env pull)YesNo

    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:

    Terminal
    $ 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:

    Terminal
    $ orbits login --with-token < token.txt$ orbits whoami

    In scripts and CI, set ORBITS_TOKEN instead. It is used in place of any stored sign-in, and nothing is written to disk:

    Terminal
    $ export ORBITS_TOKEN=orb_live_…$ orbits --project storefront deploy ./dist --no-logs

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

    .github/workflows/deploy.yml
    - name: Deploy to Orbits
      env:
        ORBITS_TOKEN: ${{ secrets.ORBITS_TOKEN }}
      run: orbits --project storefront deploy ./dist --no-logs

    Give 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}/tokensThe list
    POST /v1/teams/{team}/tokensCreate 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.

    Was this page helpful?

    Updated