Skip to content

Authentication & API tokens

View as Markdown

Colophon’s delivery API needs no credential: published content is public. Everything else, reading drafts and writing, needs one. Scripts, site builds and other tools use a project API token; people use their own sign-in.

Credential Looks like Who it is Works on
None Anyone The delivery API (/content/v1), media (/media/v1), /version, /openapi.json, /livez, /readyz
Project API token colophon_api_ and 43 more characters The token itself, an identity of its own Its own project’s content routes, /api/v1/projects/{project}/environments/{environment}/…, and POST /api/v1/rich-text/validate
Personal access token an opaque string from colophon login A person, with their roles Every management route that person may use, for 30 days
Browser session the colophon_session cookie A person signed in to the Studio Every management route; writes also need X-CSRF-Token and a trusted Origin
Site user session a bearer token or the colophon_audience cookie One of your website’s visitors Gated content on the delivery API, and the audience routes
Preview token cpv_ and more Whoever opened the preview /preview/v1, for one entry or publish request, for 15 minutes

This page is about the first three. Site user sessions are covered with gated content; preview tokens with Preview.

Send the token in the Authorization header

Section titled “Send the token in the Authorization header”

Every token goes in one header, the same way for every route that takes it:

Authorization: Bearer colophon_api_…

There is no query-string form and no custom header: a credential in a URL ends up in logs and browser history.

The management API. Ask the server what this token may do:

Terminal window
curl -i "http://localhost:8080/api/v1/projects/$PROJECT/environments/production/permissions" \
-H "Authorization: Bearer $COLOPHON_TOKEN"
Response: 200 OK, a full-access token’s permissions
HTTP/1.1 200 OK
content-type: application/json
x-request-id: 01a1ee74-3bf3-7597-a87a-abcbcf101b69
content-length: 392
date: Wed, 18 Nov 2026 11:39:17 GMT
{
"data": {
"kind": "token",
"role": null,
"permissions": [
{
"action": "content.read",
"subject": "*"
},
{
"action": "content.create",
"subject": "*"
},
{
"action": "content.update",
"subject": "*"
},
{
"action": "content.delete",
"subject": "*"
},
{
"action": "content.review",
"subject": "*"
},
{
"action": "content.publish",
"subject": "*"
},
{
"action": "schema.change",
"subject": "*"
},
{
"action": "destinations.manage",
"subject": "*"
}
]
}
}

GraphQL takes the same header on POST …/collections/{collection}/graphql:

Terminal window
curl "http://localhost:8080/api/v1/projects/$PROJECT/environments/production/collections/recipes/graphql" \
-H "Authorization: Bearer $COLOPHON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"query": "{ entries(first: 5) { nodes { id title } } }"}'

Live events too, on the signed-in stream (curl -N keeps the stream open):

Terminal window
curl -N "http://localhost:8080/api/v1/projects/$PROJECT/environments/production/events" \
-H "Authorization: Bearer $COLOPHON_TOKEN"

The delivery API takes no token. If you send one anyway it is ignored and the read is anonymous; it never unlocks drafts or gated content.

The SDK attaches it for you: new Client({ baseUrl, token: process.env.COLOPHON_TOKEN }).

A project API token belongs to one project. It holds permissions the way a role does, it ends on a date you choose, and anything it writes is recorded as written by that token, not by the person who made it.

You need a role that manages API tokens; owners do by default.

  1. Open the project’s Settings → API tokens and press New token.
  2. Give it a Name that says what uses it (Site build, Import script): it is how you’ll know which one to revoke. A Description is optional.
  3. Choose What it may do: Read only, Full access or Custom (below).
  4. Choose how long it Works for: 7 days, 30 days, 90 days, 6 months or a year.
  5. Press Make the token, then Copy the token. It is shown once: Colophon stores only its SHA-256 fingerprint, so a lost token can’t be shown again. Revoke it and make another.

The list shows each token’s state (Active, Ended or Revoked), what it may do, when it was last used, when it stops working and who made it.

In the Studio kind in the API Permissions
Read only read-only content.read on every content type: sees every entry, drafts included, and changes nothing
Full access full-access Every action a token may hold, on everything: content.read, content.create, content.update, content.delete, content.review, content.publish, schema.change, destinations.manage
Custom custom Exactly the permissions you list, each for every content type (*) or one content type, optionally narrowed to some fields or to the token’s own entries

A token can never hold more than the person making it may do. Making a token with a power your role lacks is refused with 403 and details.reason cannot_grant.

Between 1 and 366 days (expires_in_days); the Studio offers 7, 30, 90, 180 and 365. After that the token answers 401 unauthorized, exactly as a revoked one does, and the Studio shows it as Ended. To replace a token without downtime, make the new one, switch your site or script to it, then revoke the old one.

A project holds at most 100 active tokens; one more is refused with 422 and too_many_tokens.

The token routes are for people: they take a personal access token or a browser session, never an API token. Here the project’s owner makes a read-only token for a nightly site build:

Terminal window
curl -i -X POST "http://localhost:8080/api/v1/projects/$PROJECT/tokens" \
-H "Authorization: Bearer $PERSONAL_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Nightly build", "kind": "read-only", "expires_in_days": 30}'
Response: 201 Created, with the secret
HTTP/1.1 201 Created
content-type: application/json
x-request-id: 01a1ee74-3c85-767b-b1c0-c10310722d09
content-length: 527
date: Wed, 18 Nov 2026 11:39:17 GMT
{
"data": {
"id": "01a1ee74-3c87-7615-b145-77e406400537",
"identity_id": "01a1ee74-3c87-7615-b145-77e5fe9fe634",
"name": "Nightly build",
"description": "",
"kind": "read-only",
"permissions": [
{
"action": "content.read",
"subject": "*"
}
],
"state": "active",
"created_by": {
"id": "01a1ee74-2549-74be-9e59-754b0adafad3",
"name": "Akira Shirase"
},
"created_at": "2026-11-18T11:39:17.511009Z",
"expires_at": "2026-12-18T11:39:17.511884Z",
"last_used_at": null,
"revoked_at": null,
"limits": null,
"secret": "colophon_api_LGoSTqAWrhLQl7L67mVV97EV0qJCsyHL84u-Mfxq5QY"
}
}

secret appears in this answer and nowhere else. Keep it, and the token’s id, for the steps below:

Terminal window
export BUILD_TOKEN='colophon_api_…' # data.secret
export BUILD_TOKEN_ID='…' # data.id

PERSONAL_TOKEN here is the owner’s personal access token. colophon login --server http://localhost:8080 gets one through a browser approval and keeps it in ~/.config/colophon/credentials.json; see CLI.

A custom token lists its permissions. Each is an action and a subject (* or a content type’s address name), with optional fields and condition: "own". This one may read recipes and create new ones, and nothing else:

{
"name": "Recipe importer",
"kind": "custom",
"expires_in_days": 7,
"permissions": [
{ "action": "content.read", "subject": "recipes" },
{ "action": "content.create", "subject": "recipes" }
]
}

A token can also carry ceilings on its own work, as limits when it is made or later with PATCH. The Studio doesn’t set them yet; use the API.

Limit Range What happens over it
requests_per_minute 1 to 100,000 429 rate_limited with Retry-After, before the request does any work
documents_per_day 1 to 1,000,000 Entry creates, saves, translations and imported items over it: 403 with budget_exceeded
max_concurrent_jobs 1 to 64 A publish whose website deliveries would hold more jobs at once: 403 with budget_exceeded
tokens_per_day, cost_per_day_micros 1 to 1,000,000,000; 1 to 100,000,000,000 Ceilings for AI model calls, in model tokens and in millionths of a currency unit. Accepted and stored; nothing in Colophon spends against them yet

Days and minutes are rolling windows. A limit you leave out is unconstrained; {"limits": null} removes them all. Give the nightly build token a ceiling of two requests a minute:

Terminal window
curl -s -X PATCH "http://localhost:8080/api/v1/projects/$PROJECT/tokens/$BUILD_TOKEN_ID" \
-H "Authorization: Bearer $PERSONAL_TOKEN" \
-H "Content-Type: application/json" \
-d '{"limits": {"requests_per_minute": 2}}' | grep -o '"limits":{[^}]*}'
"limits":{"documents_per_day":null,"max_concurrent_jobs":null,"requests_per_minute":2,"tokens_per_day":null,"cost_per_day_micros":null}

Three reads in a row: the third is over the ceiling.

Terminal window
for attempt in 1 2 3; do
curl -s -o /dev/null -w "%{http_code}\n" \
"http://localhost:8080/api/v1/projects/$PROJECT/environments/production/collections/recipes/entries" \
-H "Authorization: Bearer $BUILD_TOKEN"
done
200
200
429

The refusal says when to try again, in seconds:

Terminal window
curl -i "http://localhost:8080/api/v1/projects/$PROJECT/environments/production/collections/recipes/entries" \
-H "Authorization: Bearer $BUILD_TOKEN"
HTTP/1.1 429 Too Many Requests
content-type: application/json
retry-after: 30
x-request-id: 01a1ee74-3cf5-75b9-9fc9-28e8a1c17f35
content-length: 191
date: Wed, 18 Nov 2026 11:39:17 GMT
{
"error": {
"code": "rate_limited",
"message": "too many requests; try again in 30 second(s)",
"details": {
"reason": "rate_limited",
"pointer": ""
},
"request_id": "01a1ee74-3cf5-75b9-9fc9-28e8a1c17f35"
}
}

A token can’t read or change its own limits. A person reads them, with what the token has used, from GET /api/v1/projects/{project}/tokens/{token} (limits and usage). Every change to a token’s limits is recorded in the project’s activity log, and so is the first refusal of each run of refusals.

In the Studio, press Revoke beside the token and confirm with Revoke it. With the API, a person sends DELETE:

Terminal window
curl -s -X DELETE "http://localhost:8080/api/v1/projects/$PROJECT/tokens/$BUILD_TOKEN_ID" \
-H "Authorization: Bearer $PERSONAL_TOKEN" | grep -o '"state":"[a-z]*"'
"state":"revoked"

Revoking is exact. It waits for requests already running under the token to finish, and once it has committed no new request starts: the next one is refused.

Terminal window
curl -i "http://localhost:8080/api/v1/projects/$PROJECT/environments/production/collections/recipes/entries" \
-H "Authorization: Bearer $BUILD_TOKEN"
HTTP/1.1 401 Unauthorized
content-type: application/json
x-request-id: 01a1ee74-3d18-7462-a7f9-a90242bb3782
content-length: 111
date: Wed, 18 Nov 2026 11:39:17 GMT
{
"error": {
"code": "unauthorized",
"message": "sign in first",
"request_id": "01a1ee74-3d18-7462-a7f9-a90242bb3782"
}
}

What the token already did stays in the activity log, under its name. Revoking can’t be undone.

A token is for content. These stay with people, whatever the token’s kind:

  • Manage access, or read the record of it. No token may hold members.manage, roles.manage, tokens.manage or audit.read, and the database refuses them too. A leaked token can’t make another token, invite anyone, raise a role or read what it did.
  • Use the people routes: /me, the project list, members, invitations, roles, tokens and the activity log answer 403 with api_token_not_allowed.
  • Approve a publish request that a token sent for review. Any token approving any token’s request is refused with 403 and agent_self_review: a person has to approve. A token may still publish a request a person approved, and may request changes. See Management API.
  • Schedule a publish. A schedule runs later as the person who made it, so tokens get api_token_not_allowed.
  • Open a preview. Previews show drafts to people; tokens are refused.
  • Reach another project. Another project’s routes answer 404, the same as a project that doesn’t exist, so a token can’t find out what else is on the server.
  • Do more than its maker. A token never holds a power its maker’s role didn’t have when it was made.

A token on a people route:

Terminal window
curl -i "http://localhost:8080/api/v1/projects/$PROJECT/members" \
-H "Authorization: Bearer $COLOPHON_TOKEN"
HTTP/1.1 403 Forbidden
content-type: application/json
x-request-id: 01a1ee74-3d27-7348-b93d-7dd515862d84
content-length: 262
date: Wed, 18 Nov 2026 11:39:17 GMT
{
"error": {
"code": "forbidden",
"message": "an API token works only with its project's content; members, roles, tokens and the audit log stay with people",
"details": {
"reason": "api_token_not_allowed",
"pointer": ""
},
"request_id": "01a1ee74-3d27-7348-b93d-7dd515862d84"
}
}

A token on a project that isn’t its own:

Terminal window
curl -i "http://localhost:8080/api/v1/projects/01a1ee5f-0000-7000-8000-000000000000/environments/production/collections/recipes/entries" \
-H "Authorization: Bearer $COLOPHON_TOKEN"
HTTP/1.1 404 Not Found
content-type: application/json
x-request-id: 01a1ee74-3d37-72f0-9a51-5da251070a78
content-length: 111
date: Wed, 18 Nov 2026 11:39:17 GMT
{
"error": {
"code": "not_found",
"message": "no such resource",
"request_id": "01a1ee74-3d37-72f0-9a51-5da251070a78"
}
}

A token is a password for your project’s content. Treat it like one:

  • Put it in a server’s environment or a secret store, and read it from there (process.env.COLOPHON_TOKEN). Never commit it, and never put it in front-end code, a browser bundle, a mobile app or a public build log.
  • A website reads published content from the delivery API with no token. If a page needs drafts, render it on a server; to show editors a draft on the site, use Preview, whose tokens are short-lived and read one entry.
  • Give each script or site its own token with the least it needs, so you can revoke one without stopping the rest. Prefer Read only or Custom over Full access, and short lifetimes over long ones.
  • The colophon_api_ prefix lets secret scanners recognise a leaked token. If one leaks, revoke it at once and check the activity log for what it did.

Every server counts requests, shared across servers through Valkey when there are several:

Counted per Covers Default
Client address The management API and sign-in (/api/, /auth/) 300 requests a second, bursts of 600
Credential The same routes, per token, cookie or personal token 150 requests a second, bursts of 300
Client address The delivery API (/content/) 1,000 requests a second, bursts of 2,000

Over a limit, the answer is 429 with rate_limited and a Retry-After header, before the request does any work. A token’s own requests_per_minute applies on top. Health checks, /version and the Studio’s files are never counted. Operators change these; see Rate limits.

Every refusal is the same envelope: code for the kind, details.reason where there is one, a message safe to show a person, and the request id. Branch on code and details.reason.

Status code details.reason When
401 unauthorized No credential, a malformed or unknown one, a revoked or expired token
403 forbidden api_token_not_allowed A token on a people route, scheduling or previews
403 forbidden missing_permission The token lacks the permission; details.permission names it
403 forbidden agent_self_review A token approving a publish request a token sent
403 forbidden budget_exceeded Over documents_per_day or max_concurrent_jobs
403 forbidden cannot_grant Making a token with a power you don’t have
404 not_found Another project, or something the token may not see
422 validation_failed invalid_expiry, permissions_required, too_many_tokens, invalid_limit A token the API refuses to make or change
429 rate_limited rate_limited Over a rate limit; wait Retry-After seconds

No credential at all:

Terminal window
curl -i "http://localhost:8080/api/v1/projects/$PROJECT/environments/production/collections/recipes/entries"
HTTP/1.1 401 Unauthorized
content-type: application/json
x-request-id: 01a1ee74-3d48-746a-91f9-41238360c59d
content-length: 111
date: Wed, 18 Nov 2026 11:39:17 GMT
{
"error": {
"code": "unauthorized",
"message": "sign in first",
"request_id": "01a1ee74-3d48-746a-91f9-41238360c59d"
}
}

A read-only token trying to write, which also shows details.permission. Make a read-only token in the Studio and send a create with it:

Terminal window
curl -i -X POST "http://localhost:8080/api/v1/projects/$PROJECT/environments/production/collections/recipes/entries" \
-H "Authorization: Bearer $READ_ONLY_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: create-scones-00001" \
-d '{"dish": "Scones"}'
HTTP/1.1 403 Forbidden
content-type: application/json
x-request-id: 01a1ee74-3d6c-7367-8172-85f5fd8d1bf5
content-length: 215
date: Wed, 18 Nov 2026 11:39:17 GMT
{
"error": {
"code": "forbidden",
"message": "your role can't create entries here",
"details": {
"reason": "missing_permission",
"pointer": "",
"permission": "content.create"
},
"request_id": "01a1ee74-3d6c-7367-8172-85f5fd8d1bf5"
}
}

The full list of codes is on Errors.

People: personal access tokens and sessions

Section titled “People: personal access tokens and sessions”
  • colophon login signs the CLI in through the browser: it shows a code, you approve it in the Studio where you’re signed in, and the CLI receives a personal access token that acts as you for 30 days. colophon logout revokes it. The SDK and curl can use the same token as a bearer token.
  • The Studio uses a session cookie. Writes made with a cookie must also send the colophon_csrf cookie’s value as X-CSRF-Token, from an Origin the server trusts exactly; bearer tokens need neither, since a browser never attaches them by itself.

Only people can approve their own work where their role allows it, manage access and schedule publishing.

Was this page helpful?

Either answer opens a short issue on GitHub, so you can say what worked or what was missing.