Skip to content

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 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.

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:

  • reconcile always needs entities: write and entities: delete, even if the run ends up deleting nothing, because a reconcile can delete.
  • Impact analysis needs policies: write, not read, 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 with 400.
  • App tokens can call only the endpoints in API endpoints. Everything else is done in the Console.
  1. In the Console, open the Organization page.

  2. In the App tokens section, select Create app token.

  3. 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.
  4. Copy the token.

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.

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.

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.

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:

  1. Create a new token with the settings you want.
  2. Switch your service to the new token.
  3. Revoke the old one.
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.

  • One token per integration, scoped to one project, with only the verbs it needs.
  • Grant delete only 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.