Authentication

Updated 9/17/2026

Authentication

LetterAPI authenticates requests with an API key sent as a bearer token.

Authorization: Bearer la_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Creating a key

Create and revoke keys from Dashboard → Settings → API keys, or via the account API itself (requires an existing session or key):

GET    /api/v1/account/api-keys
POST   /api/v1/account/api-keys
DELETE /api/v1/account/api-keys/{id}

POST /api/v1/account/api-keys body:

json
{
  "label": "Production server",
  "scopes": ["*"],
  "mode": "live"
}

Field	Type	Required	Notes
`label`	string, 1–200 chars	yes	Shown in the dashboard so you can identify the key later.
`scopes`	string[]	yes	Use `["*"]` for full access. Scoped keys are supported by the schema for future use.
`mode`	`"test"` \| `"live"`	no, defaults to `"test"`	Determines the key prefix and which order/webhook data the key can see.

The response includes plaintext — the full key is only ever returned once, at creation time. Store it immediately; the dashboard and API only ever show the key_prefix (first 12 characters) afterward.

json
{
  "id": "b6c1e...",
  "plaintext": "la_live_9f2c...redacted",
  "prefix": "la_live_9f2c",
  "label": "Production server",
  "scopes": ["*"],
  "mode": "live",
  "createdAt": "2026-01-14T10:02:00.000Z"
}

Key format

Prefix	Mode	Meaning
`la_live_…`	live	Real orders, real payment, real post.
`la_test_…`	test	Simulated payment, no real print/post dispatch, isolated test webhooks.

Keys are stored server-side as a SHA-256 hash — LetterAPI itself cannot recover a lost plaintext key. Revoke it and create a new one instead.

Revoking a key

DELETE /api/v1/account/api-keys/{id}

Returns 204 No Content. A revoked key immediately stops authenticating requests.

Session auth (dashboard only)

Requests made from an authenticated browser session (i.e. while logged into the dashboard) are also accepted without a bearer token, scoped to live mode. This exists to let the dashboard UI call the same /api/v1/* endpoints your integration uses — for server-to-server integrations, always use an API key.

Errors

Status	Meaning
`401 Unauthorized`	Missing, invalid, or revoked API key.

LetterAPIPrint and post letters in the UK, from one letter to thousands.