> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/reference/admin-api/personal-access-tokens.md).

# Personal access tokens

Get, rotate and revoke the tokens that authenticate the Admin API, the Terra CLI and MCP clients.

A personal access token authenticates you to the Admin API. Every request carries one, and it acts as you with the [scopes](https://docs.tryterra.co/reference/admin-api/scopes.md) you approved.

| Property    | Value                                                                                           |
| ----------- | ----------------------------------------------------------------------------------------------- |
| Prefix      | `terra_at_`                                                                                     |
| Header      | `Authorization: Bearer <TOKEN>`                                                                 |
| Lifetime    | 30 days from `terra login` or an MCP client. 7, 30, 60 or 90 days when minted in the dashboard. |
| Renewal     | Rotate it up to 90 days after it was first issued. After that, sign in again.                   |
| Limit       | 25 live tokens per account.                                                                     |
| Accepted by | The Admin API only. The data APIs reject it.                                                    |

## Get a token

| From       | How you approve it                                       | Lifetime             |
| ---------- | -------------------------------------------------------- | -------------------- |
| Terra CLI  | `terra login` opens the dashboard with a pairing code.   | 30 days              |
| MCP client | Connecting the client opens the dashboard to approve it. | 30 days              |
| Dashboard  | **Settings > Personal Access Tokens > Mint Token**.      | 7, 30, 60 or 90 days |

On the approval page you pick a preset or set each scope yourself. See [Scopes](https://docs.tryterra.co/reference/admin-api/scopes.md#presets).

```bash
terra login
```

`terra login --scope <SCOPES>` asks for exactly those scopes. `terra login --env <DEV_ID>` limits the token to that environment. For CI and other places where no one can approve in a browser, mint a token in the dashboard and set it as `TERRA_ADMIN_TOKEN`. See [Authentication](https://docs.tryterra.co/developer-tools/terra-cli/authentication).

The CLI and MCP clients use OAuth on your behalf: the device flow (`POST /auth/device`, then `POST /auth/token`) for the CLI, and the authorization code flow with PKCE (`GET /auth/authorize`, then `POST /auth/token`) for MCP clients. Neither issues a refresh token. Rotate instead.

## Check a token

```http
GET /me
```

```bash
terra account retrieve
```

Returns the calling token's `scopes`, `dev_ids`, `expires_at`, `grant_anchor_at` and the user it acts as. Needs no scope.

## Rotate a token

```http
POST /tokens/self/rotate
```

```bash
terra tokens rotate
```

Swaps the calling token for a new one and returns the new token once. The old token stops working. Rotation works until 90 days after the token was first issued (`grant_anchor_at`). A rotation near that limit gets a shorter expiry, and one past it returns `409`. Read `expires_at`, `scopes` and `dev_ids` from the response. Needs no scope, and accepts `?dry_run=true`.

## Revoke a token

To revoke the token you are using:

```http
DELETE /tokens/self
```

```bash
terra logout
```

`terra logout` revokes the token the CLI stored. It does not revoke a token set in `TERRA_ADMIN_TOKEN`.

To revoke any token on your account, use its ID:

```http
DELETE /tokens/{token_id}
```

```bash
terra tokens delete <token_id>
```

This needs `tokens:admin`. Account admins can also revoke any token from **Settings > Personal Access Tokens**. Revocation takes effect on the token's next request.

## List tokens

```http
GET /tokens
```

```bash
terra tokens list
```

Lists every personal access token on your account and how each was created. Needs `tokens:admin`.

## Permissions

A token can never do more than your team role allows. Account admins can grant any scope. Other roles cannot grant the scopes that are [off by default](https://docs.tryterra.co/reference/admin-api/scopes.md#off-by-default).

Every token you created stops working if you are removed from the team, move to another company or your role is lowered.

A token limited to some environments gets `403` with `code: audience_restricted` for any other environment, and cannot hold [account-wide scopes](https://docs.tryterra.co/reference/admin-api/scopes.md#account-wide-scopes).

## See also

* [Scopes](https://docs.tryterra.co/reference/admin-api/scopes.md)
* [Terra CLI authentication](https://docs.tryterra.co/developer-tools/terra-cli/authentication)
* [MCP server](https://docs.tryterra.co/developer-tools/mcp-server)
