API keys, scopes and platform constraints
Every request to either API is authenticated by a key, and every key carries scopes that decide what it can do. The two APIs look different at the wire — a header versus a path segment — but they are issued, checked and retired by the same system underneath.
Before you read this
The quickstart already put a bearer token in a request header without explaining its shape or what it is allowed to do — this page fills that in. Revisit the first API request
The shape of a v3 token
A v3 key is sent as a standard bearer token, with a fixed prefix that identifies it as a Livstick key before the secret half:
Authorization: Bearer liv_<prefix>_<secret>- liv_ marks the token as a Livstick key, at a glance in logs and support tickets.
- <prefix> identifies the key without exposing the secret — it is safe to log or display.
- <secret> is the part that authenticates the request, and the only part that must stay confidential.
The nine v3 scopes
A v3 key is granted one or more of nine scopes. Each scope maps to a slice of the container and message surface, not to a single endpoint — containers:read, for instance, covers both listing and reading a single container.
| Scope | Grants |
|---|---|
| containers:read | List containers, read a single container, and retrieve its recording and preview URLs. |
| containers:write | Create or retrieve a container, and correct it with a partial update. |
| containers:notify | Trigger delivery to the recipient. |
| containers:unlock | Make a message accessible to its recipient. |
| containers:qrcode | Retrieve the container's QR code as a PNG. |
| containers:card | Retrieve the container's printable card as a PDF. |
| messages:read | Read messages, filtered by container id or by code group. |
| messages:write | Update a message's data and privateData. |
| code_groups:read | Read the list of code groups. |
Four scopes added for API v3.1
API v3.1 reuses the containers:* and messages:read scopes listed above, for the same operations, and adds four. A key that must call one of the new routes needs its scope when it is created: a scope cannot be added to an existing key, so create a new key and retire the old one.
| Scope | Grants |
|---|---|
| tokens:record | Mint record tokens, which let the recording widget write one message for one mrid. |
| tokens:view | Mint view tokens, which let the viewing widget read one message or a whole container. |
| messages:publish | Release a held message, and delete a message for a refund or a withdrawal. |
| webhooks:read | Read the delivery log of your platform. |
The two 2.1 scopes
The 2.1 API does not split permissions by operation the way v3 does. It grants access by route family instead, one scope per family: client_v2 for the client-facing /v2.1/client/… routes, user_v2 for the recipient-facing /v2.1/user/… route.
| Scope | Grants |
|---|---|
| client_v2 | Every /v2.1/client/{key}/{crid}/… route: redirect, retarget, QR code, card, notify, modify, details, webhook registration. |
| user_v2 | The recipient-facing /v2.1/user/{key}/{crid}/redirect route. |
One key system for both APIs
This is the fact worth carrying forward: v3 and 2.1 are not two credential systems bolted together. A key — whichever API it targets — is managed through the same infrastructure underneath.
- Secrets are stored hashed, never in a form that could be read back.
- A key can carry an expiration, and its status (active, revoked, expired) is checked on every request.
- Every use is audited, and lastUsedAt is kept up to date for each key.
- A key can be constrained to a platform, in addition to its scopes.
Where to see your actual scopes
This page lists what exists — every scope either API defines, and the shape a key takes. It does not, and cannot, tell you which scopes your own keys hold, or show you a key's actual value.