App tokens
App tokens are the machine credentials your services, sync jobs, and CI pipelines use to call the Control Plane API. Each token is a JWT that is:
- scoped to your whole organization or to a single project;
- limited by a permission map that lists exactly which resources it may read, write, or delete;
- always expiring, because a token cannot be created without an expiry date.
Send it on every request as Authorization: Bearer <token>, together with the required x-op-id and x-session-id headers.
Scope: organization or project
Section titled “Scope: organization or project”| Scope | Create with | Can act on |
|---|---|---|
| Project | A project selected | That one project only. It can never reach a sibling project, even within the same organization. |
| Organization | No project selected | Every project in the organization. |
Prefer project-scoped tokens. Give each integration its own token for the one project it works on.
An organization-scoped token calling a body-based ingest endpoint (/projects/entities/batch, /validate, /reconcile) must name the target project as projectId in the request body. A projectId in the query string is rejected with 403.
Permissions
Section titled “Permissions”The permissions object maps a resource to the verbs the token is granted. At least one resource is required, and each listed resource needs at least one verb.
{ "entities": ["read", "write", "delete"], "schema": ["read"], "audit": ["read"]}| Resource | Verb | What it unlocks |
|---|---|---|
entities |
read |
List, read, and search entities: GET /projects/:projectId/entities, /entityList, /entity, /search-entities |
write |
Create and update single entities (POST/PUT /projects/:projectId/entity), POST /projects/entities/batch (without deletes), POST /projects/entities/validate |
|
delete |
DELETE /projects/:projectId/entity, and any batch containing a delete operation (together with write) |
|
policies |
read |
List and read policies and their versions: GET /projects/:projectId/policies, /policyList, /policy |
write |
Create and update policies (POST/PUT /projects/:projectId/policy), and run impact analysis (POST /projects/:projectId/policy/analyze) |
|
delete |
DELETE /projects/:projectId/policy |
|
schema |
read |
GET /projects/:projectId/schema |
write |
PUT /projects/:projectId/schema |
|
projects |
read |
List projects (GET /projects, limited to the token’s scope) and read the PDP attachment (GET /pdp/shared) |
write |
Create projects (POST /projects), update project details (PATCH /projects/:projectId/attributes), attach a project to a shared PDP (POST /pdp/shared) |
|
audit |
read |
GET /audit/events and GET /audit/summary |
inline_entities |
assert |
Send inline resource entities to the PDP’s /authorize, as the X-App-Token header |
tests, test_data |
read, write, delete |
Accepted, but no endpoint currently honors them for app tokens. |
Things to know:
reconcilealways needsentities: writeandentities: delete, even if the run ends up deleting nothing, because a reconcile can delete.- Impact analysis needs
policies: write, notread, even though it saves nothing. - Duplicate verbs are ignored. An unknown resource or a verb a resource doesn’t support (for example
schema: ["delete"]) is rejected with400. - App tokens can call only the endpoints in API endpoints. Everything else is done in the Console.
Create a token
Section titled “Create a token”-
In the Console, open the Organization page.
-
In the App tokens section, select Create app token.
-
Choose the settings:
Setting Required Notes Expiry Yes Must be in the future. Permissions Yes See Permissions. Project No Leave empty for an organization-scoped token. Description No A label shown in the token list. -
Copy the token.
List tokens
Section titled “List tokens”The App tokens section lists every token in the organization, newest first, including revoked ones. Secrets are never shown in the list.
A token is usable until its expiry date. A request with an expired token is rejected with 401.
Rotate a token
Section titled “Rotate a token”Select Rotate token on the token.
Rotation issues a new secret for the same token. The token keeps its ID, scope, permissions, and expiry date. The old secret stops working immediately.
- You cannot rotate a revoked token.
- You cannot rotate an expired token. Create a new token instead.
- Rotation does not extend the expiry.
Rotate whenever a secret may have leaked, or on a schedule. The old secret is invalid from the moment rotation succeeds, so roll out the new one straight away.
Revoke a token
Section titled “Revoke a token”Select Revoke token on the token.
Revocation permanently disables the token. Requests made with it are rejected immediately. The token stays in the list as revoked, for your records. Revocation cannot be undone.
Changing a token
Section titled “Changing a token”You cannot edit or delete a token. A token’s scope, permissions, and expiry are fixed when it is created. To change any of them:
- Create a new token with the settings you want.
- Switch your service to the new token.
- Revoke the old one.
Errors and limits
Section titled “Errors and limits”| Status | When |
|---|---|
400 |
Invalid request body. |
401 |
Missing, malformed, expired, rotated-out, or revoked token. |
403 |
Calling an endpoint the token’s grants don’t cover; a project-scoped token targeting another project; projectId in the query string on an ingest endpoint. |
404 |
A projectId outside your organization. |
429 |
Rate limit reached. |
The entity ingest endpoints (batch, validate, reconcile) are rate-limited to 120 requests per minute per token, and other endpoints have a broad per-IP safety limit. 429 responses include standard RateLimit headers. The TypeScript SDK retries 429 automatically, honoring Retry-After.
Good practice
Section titled “Good practice”- One token per integration, scoped to one project, with only the verbs it needs.
- Grant
deleteonly to jobs that must delete (for example, a reconcile job). - Pick the shortest expiry you can operate with, and track expiry dates in the App tokens section.
- Keep tokens out of command lines and source code: use environment variables (for example
ZSTRIKE_APP_TOKEN) or a secret manager.