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

    HTTP
    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) or read (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

    readfull
    GET and HEAD requestsYesYes
    Anything else (create, change, delete, deploy)No: 403 "This API token is read-only"Yes
    Environment variable valuesNever (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}.

    Was this page helpful?

    Updated