> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tofunmiadewuyi.com/custos/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Authentication, token lifecycle, payload encryption, and error conventions.

The control plane is a JSON HTTP API. Everything the frontend and the CLI do goes through it; the
only non-HTTP surface is the daemon WebSocket, documented in
[Daemon protocol](/custos/custos/internals/daemon-protocol).

<Note>
  The endpoint pages in this tab are generated from a seed OpenAPI specification that currently covers
  auth, identity, keys, host listing, and grants. The remaining control-plane endpoints — credentials,
  sets, groups, backup jobs, users, invitations, notifications, and audit — are being transcribed.
</Note>

## Authentication

Send an opaque access token as a bearer header:

```http theme={null}
Authorization: Bearer <access_token>
```

Get one from `POST /login`. Both token types are opaque and checked against the database on every
request, which makes revocation immediate — the tradeoff Custos takes deliberately for a secrets
vault with low request volume.

| Token | Lifetime | Notes |
| - | - | - |
| access | 15 minutes | sent on every request; the response's `expires_in` reports this in seconds |
| refresh | 30 days | rotated on every use |

`expires_in` is a **duration, not a timestamp** — add it to your own clock rather than parsing a
server time.

<Warning>
  `POST /refresh` returns a **new refresh token** alongside the new access token, and invalidates the
  one you sent. A client that stores only the access token from a refresh response will fail on its
  next refresh.
</Warning>

## Roles

Every caller is either an `admin` or a `member`. Admins bypass grant resolution. Members act through
grants — see [Permissions](/custos/custos/concepts/permissions). Endpoints self-gate on the relevant permission
rather than on role, so most of the API is usable by members with the right grants.

## Payload encryption

`CUSTOS_ENCRYPTION` on the control plane decides whether bodies are sealed. **If it is off, send and
read plain JSON and there is nothing to implement.** If it is on, request and response bodies are
sealed with a hybrid X25519 scheme on top of TLS, and your client has to match — see
[Encrypted transport](/custos/custos/api-reference/encryption) for the full contract.

Either way, the bodies on these pages describe the **plaintext** shapes, before any sealing.

<Warning>
  The interactive playground sends plain JSON, so it only works against a control plane started with
  `CUSTOS_ENCRYPTION=off` — the usual local development setting. Turning it off disables neither
  HTTPS/TLS nor at-rest vault encryption.
</Warning>

## Rate limits

Unauthenticated endpoints — login, refresh, enroll, invitation acceptance, and password reset — are
rate-limited per IP at roughly 10 requests per minute. Login additionally throttles per account: 5
failures within 15 minutes locks that account for 15 minutes, clearing on window expiry or a
successful login. Both return `429`.

The per-account window is deliberately not a hard lockout, which would turn the endpoint into a
targeted denial-of-service tool.

## Errors

Failures return the appropriate status code with a plain-text message body. `500` responses carry a
generic message; the real cause is logged server-side with its trace and span id.

Conventions worth knowing:

* `403` means authenticated but not permitted — usually a missing grant.
* `409` on enrollment means that machine already has an active host.
* `503` means a dependency is unavailable; for secret endpoints, that the vault key wrapper is not
  configured.
* Password reset always returns `204`, whether or not the address exists, to avoid leaking which
  accounts are registered.

## Health

`GET /livez`, `GET /readyz`, and `GET /healthz` need no authentication. See
[Install the control plane](/custos/custos/control-plane/install).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.