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

Source: https://docs.orbits.africa/api/authentication

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](https://docs.orbits.africa/team/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 `POST`s) | 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}`.

:::warning[Treat a token like a password]
Anyone with a `full` token can deploy to your production and read your environment variables. Give each script or CI pipeline its own token, with `read` access or one project where that is enough, and revoke a token you no longer use, or that may have leaked, under **Team › Settings › API tokens**.
:::
