+++
title = "Account and tokens"
description = "The account an API token belongs to, and the token itself."
weight = 85
updated = 2026-11-03

[extra]
nav_title = "Account and tokens"
weight = 10
+++

<!-- Generated by script/build-api-reference.js from data/openapi/v1.yml and data/api-reference/pages.yml. Edit those and run `npm run build:api-reference`, not this file. -->

The account an API token belongs to, and the token itself. `GET /v1`
needs no token, so it also serves as a health check. See
[Authentication](@/docs/api/authentication/index.md) for how tokens
and scopes work.

**On this page:** [Account object](#account-object), [Token object](#token-object), [Show the API's version and links](#get-api-root), [Show the token's account](#get-account), [Show the calling token](#get-token), [Revoke the calling token](#revoke-token).

## The Account object {#account-object}

| Field | Type | Description |
|---|---|---|
| `id` | string | The account's slug. Never changes. |
| `name` | string | The account's name. |
| `contact_email_override` | string or null | When set, the only address that gets cluster notifications and billing email. null to use the default. |
| `created_at` | string (date-time) | When it was created. |

```json
{
  "id": "acme",
  "name": "Acme",
  "contact_email_override": null,
  "created_at": "2024-03-12T09:30:00Z"
}
```

## The Token object {#token-object}

| Field | Type | Description |
|---|---|---|
| `key` | string | The token's public half: `<key>` in `bonsai_<key>_<secret>`. The dashboard lists tokens by it. |
| `name` | string or null | The token's name, or null. |
| `account` | object | The account the token belongs to. |
| `account.id` | string | The account's ID. |
| `account.name` | string | The account's name. |
| `scopes` | array of strings | The scopes the token holds. See [Scopes](@/docs/api/authentication/index.md#scopes). |
| `expires_at` | string (date-time) or null | null for a token that never expires. |
| `created_at` | string (date-time) | When it was created. |

```json
{
  "key": "1a2b3c4d5e6f7a8b",
  "name": null,
  "account": { "id": "acme", "name": "Acme" },
  "scopes": ["account:read", "clusters:read", "clusters:write", "credentials:read"],
  "expires_at": null,
  "created_at": "2026-10-26T14:00:00Z"
}
```

## Show the API's version and links {#get-api-root}

<p class="api-endpoint"><span class="api-method api-method-get">GET</span> <code>/v1</code></p>

- **Token:** none needed.

Needs no token, so it also serves as a health check. Rate-limited by IP address.

### Example request

```bash
curl https://api.bonsai.io/v1/
```

### Response

`200 OK`. The API's name, version and links.

| Field | Type | Description |
|---|---|---|
| `name` | string | `Bonsai API`. |
| `version` | string | This contract's `info.version`. |
| `docs_url` | string (URL) | The API reference. |
| `openapi_url` | string (URL) | This contract as JSON. |
| `tokens_url` | string (URL) | The dashboard's API Tokens page, where a token is made by hand. It names no account: it opens the signed-in person's default account. |

```json
{
  "name": "Bonsai API",
  "version": "1.0.0",
  "docs_url": "https://bonsai.io/docs/api/",
  "openapi_url": "https://api.bonsai.io/v1/openapi.json",
  "tokens_url": "https://app.bonsai.io/api_tokens"
}
```

### Errors

| Status | Codes |
|---|---|
| `429` | [`rate_limited`](@/docs/api/errors/index.md#rate_limited) |

## Show the token's account {#get-account}

<p class="api-endpoint"><span class="api-method api-method-get">GET</span> <code>/v1/account</code></p>

- **Scope:** `account:read`

What the dashboard's account settings show every member. No billing or payment details.

### Example request

```bash
curl https://api.bonsai.io/v1/account \
  -H "Authorization: Bearer $BONSAI_TOKEN"
```

### Response

`200 OK`. The account. Returns an [Account object](#account-object).

```json
{
  "id": "acme",
  "name": "Acme",
  "contact_email_override": null,
  "created_at": "2024-03-12T09:30:00Z"
}
```

### Errors

| Status | Codes |
|---|---|
| `401` | [`unauthorized`](@/docs/api/errors/index.md#unauthorized) |
| `403` | [`missing_scope`](@/docs/api/errors/index.md#missing_scope) |
| `429` | [`rate_limited`](@/docs/api/errors/index.md#rate_limited), [`too_many_failed_authentications`](@/docs/api/errors/index.md#too_many_failed_authentications) |

## Show the calling token {#get-token}

<p class="api-endpoint"><span class="api-method api-method-get">GET</span> <code>/v1/token</code></p>

- **Scope:** none. Any valid token can call it.

Its key, scopes and expiry. Needs no scope; a token only ever reaches itself.

### Example request

```bash
curl https://api.bonsai.io/v1/token \
  -H "Authorization: Bearer $BONSAI_TOKEN"
```

### Response

`200 OK`. The token. Returns a [Token object](#token-object).

```json
{
  "key": "1a2b3c4d5e6f7a8b",
  "name": null,
  "account": { "id": "acme", "name": "Acme" },
  "scopes": ["account:read", "clusters:read", "clusters:write", "credentials:read"],
  "expires_at": null,
  "created_at": "2026-10-26T14:00:00Z"
}
```

### Errors

| Status | Codes |
|---|---|
| `401` | [`unauthorized`](@/docs/api/errors/index.md#unauthorized) |
| `429` | [`rate_limited`](@/docs/api/errors/index.md#rate_limited), [`too_many_failed_authentications`](@/docs/api/errors/index.md#too_many_failed_authentications) |

## Revoke the calling token {#revoke-token}

<p class="api-endpoint"><span class="api-method api-method-delete">DELETE</span> <code>/v1/token</code></p>

- **Scope:** none. Any valid token can call it.

As revoking it in the dashboard does. Needs no scope; a token only ever reaches itself. Every later request with it is a `401`.

### Example request

```bash
curl -X DELETE https://api.bonsai.io/v1/token \
  -H "Authorization: Bearer $BONSAI_TOKEN"
```

### Response

`204 No Content`. Revoked.

### Errors

| Status | Codes |
|---|---|
| `401` | [`unauthorized`](@/docs/api/errors/index.md#unauthorized) |
| `429` | [`rate_limited`](@/docs/api/errors/index.md#rate_limited), [`too_many_failed_authentications`](@/docs/api/errors/index.md#too_many_failed_authentications) |