Authentication

Every v3 request is authenticated by a bearer token sent in the Authorization header. The key that fails to authenticate and the key that authenticates but lacks the right scope fail in two different, distinguishable ways.

Scopes live elsewhere

This page covers the header and the failure modes. The full list of v3 scopes, the shape of a token, and how keys are managed is covered on its own page. API keys, scopes and platform constraints

The Authorization header

Send the key as a standard bearer token, in the Authorization header of every request:

http

Authorization: Bearer liv_<prefix>_<secret>

A complete example

A minimal, authenticated call against the v3 API — listing containers:

GET /containers

curl https://client-api.v5.livstick.com/api/v3/containers \
  -H "Authorization: Bearer liv_<prefix>_<secret>"

Unknown, expired or revoked keys

A key that fails to authenticate — because it does not exist, has expired, or has been revoked — is reported the same way: as UNAUTHORIZED, in the v3 error envelope.

json

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "..."
  }
}

Authenticated, but not allowed

A key that authenticates successfully can still fail a request it is not scoped or constrained for. That is a different failure — FORBIDDEN, not UNAUTHORIZED — and it means the key itself is valid.

json

{
  "error": {
    "code": "FORBIDDEN",
    "message": "..."
  }
}

UNAUTHORIZED means the key itself did not authenticate — missing, unknown, expired, revoked.
FORBIDDEN means the key authenticated, but this particular request falls outside its scopes or platform constraint.

Every operation is scoped

Authentication only confirms who is calling. What that key is allowed to do is decided operation by operation, by the scopes it carries — a key that can read containers cannot notify or unlock one unless it was granted those scopes separately.