Access Tokens
Create per-space API tokens that grant your apps, servers and the CLI exactly the access they need — published or draft content and translations, or development tools.
An access token is how anything outside the admin UI — your website, a backend, a build step, the CLI — authenticates to the Localess API. Each token belongs to one space and carries its own set of permissions, so you can give a public website read-only access to published content while a preview server or CI job gets more.
Assets are the exception: /assets/... URLs are public and never need a token.
Main Screen
Open a space and navigate to Settings → Access Tokens. The screen is available to admins and to users with the Space Management permission.
| Column | Description |
|---|---|
| Token | The first characters of the token. Use the copy button to copy the full value |
| Name | A label to tell tokens apart — e.g. website, preview, ci |
| Version | v2 for tokens with explicit permissions; v1 for legacy tokens |
| Permissions | How many permissions the token has — hover for the list |
| Usage | Where the token is safe to use, derived from its permissions — see Choosing permissions |
| Cache TTL | The token's cache duration: Default (60s), No Cache, or a number of seconds |
| Updated At | When the token was last changed |
| Action | Description |
|---|---|
| Add Token | Create a new token |
| Copy Token | Copy the full token value to the clipboard |
| Edit | Change the token's name, permissions or Cache TTL. The token value stays the same |
| Regenerate | Replace the token with a new value, keeping its name, permissions and Cache TTL. The old value stops working, so every client using it must be updated |
| Delete | Remove the token. Clients using it lose access |
Creating a Token
- Click Add Token.
- Enter a Name (3–30 characters).
- Tick at least one permission. The badge under the list shows the resulting usage category as you choose.
- Optionally set a Cache TTL.
- Click Save, then copy the token from the table.
A token is a 20-character alphanumeric string. Together with the Space ID (shown in Settings → General) it's all a client needs to call the API.
Permissions
Permissions are grouped in the token form as follows.
| Group | Permission | Grants |
|---|---|---|
| Translation | Public | Published translations |
| Translation | Draft | Draft and published translations |
| Content | Public | Published content documents and the links tree |
| Content | Draft | Draft and published content documents and the links tree |
| Development | Development Tools | Everything the CLI needs: read the space, its schemas, its OpenAPI spec and the raw values stored for a locale; push schemas and translations. Also reads draft and published content and translations |
A request for draft data — any request that passes a version query parameter — needs the matching Draft permission or Development Tools. A request without one is served published data and accepts any of the three permissions for that resource. A token that lacks the permission a request needs gets 403; a missing or unknown token gets 401.
Choosing permissions
The Usage badge sums up what a token's permissions imply:
| Usage | When | Use it from |
|---|---|---|
| Public-safe | Only Public permissions | Anywhere, including browser code and mobile apps — it only exposes what's already published |
| Server-side only | Any Draft permission | A trusted backend, a preview deployment or local development. Keep it secret: it exposes unpublished work |
| Development Tools Only | Development Tools | The CLI and other developer tooling. Keep it secret and out of application code — it can overwrite schemas and translations |
| No access | No permissions | Nothing until you add one |
Use separate tokens for separate jobs — a public-safe token for the production site, a draft token for the preview environment, a development tools token for CI — so each can be rotated or revoked on its own.
Using a Token
Reads — content, links, translations and the development tools reads — take the token in the token query parameter:
GET /api/v1/spaces/{spaceId}/contents/slugs/{slug}?token=<token>Writes — pushing schemas and translations — take it in an X-API-KEY header instead. The SDKs and the CLI handle this for you: pass the token as token when initializing an SDK (see Frameworks) or to localess login. See the API reference for every endpoint.
Only a Public-safe token may ever reach the browser. Keep Draft and Development Tools tokens in server-side environment variables.
Cache TTL
The content and translations endpoints answer with a short redirect to a versioned, long-cached file. Cache TTL sets how long, in seconds, that redirect may be cached by browsers and CDNs — in practice, how long after a publish a client may still see the previous version.
| Value | Behavior |
|---|---|
| Empty | Default — 60 seconds |
0 | No caching: every request checks for the latest version |
1–31536000 | Cache the redirect for that many seconds |
A lower value makes publishes show up sooner at the cost of more requests; a draft or preview token is a natural candidate for 0.
Rotating and Revoking
Regenerate a token when its value may have leaked, or Delete it when it's no longer needed. Either way the old value stops working — allow a few minutes for it to be rejected everywhere, as the API briefly caches token lookups. Update every client with the new value before you regenerate a token that's in use.
Legacy Tokens
Tokens created before permissions existed show as v1. A legacy token implicitly has all four Translation and Content permissions — which makes it a draft-capable, server-side token — but not Development Tools.
To bring a legacy token up to date, Edit it: the form opens with those four permissions ticked, so you can narrow them to what the token actually needs. Saving turns it into a v2 token with the same value. Regenerate also produces a v2 token, keeping the four permissions.