Token Management

Upcoming release — Zylon 1.58These docs are published ahead of release so you can prepare your API integrations. The release image is not yet available. For installations running 1.57, use the 1.57 documentation.

Use this page to pick the right token flow for your integration.

Which token do I need?

Workspace Token

Routes /api/v1/*.Automate Workspace operations — create projects, manage users, interact with ingested files, and more.

Gateway Token

Routes /api/gpt/v1/*.Call the ZylonGPT API directly, the same way you’d use the Anthropic API.

Workspace Token
Gateway Token (ZylonGPT)

This flow is for Workspace API access under /api/v1/*.

Workspace token flow does not issue tokens for direct ZylonGPT API calls under /api/gpt/v1/*.

Create a Workspace API token

Sign in to Workspace as an account that can manage API tokens.
Click the organization logo and open API Tokens.
Click Create API Token, provide a name, and save.
Copy and store the token value immediately. It is shown once.

Verify token access

Workspace endpoints under /api/v1/app/* require the x-org header.

curl "https://{BASE_URL}/api/v1/app/me" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "x-org: {org_slug}"

Example response

{
  "id": "user_4b7c2a1d9e5f3c8b",
  "org_id": "org_2f3a9d1c7b5e4a8f",
  "account_id": "acct_6c8a1f3b2d4e5f7a",
  "name": "Sasha Patel",
  "email": "sasha@auroralabs.com",
  "state": "Active",
  "roles": ["AppAdmin"],
  "created_at": "2026-02-08T14:12:45Z"
}

Revoke a Workspace token

Open API Tokens and click the trash icon on the token row.

This flow grants access to the ZylonGPT API under /api/gpt/v1/*, as well as Workspace and Backoffice APIs.

Create a Gateway token

Open Developer Console.
Select the target gateway.
Click Create API Token.
Enter a token name.
Generate the token.
Copy the token secret shown in the modal.

The token secret is shown only once. After closing the modal, it cannot be retrieved. Store it in a secure secret manager immediately.

API token scopes

Account token creation accepts these six serialized scope values:

Scope	Access
`Read.All`	Account, token, gateway, Backoffice/meta, Workspace read/search, and the ZylonGPT read-only allowlist when the token carries `gateway_id`.
`ReadWrite.All`	Read and write access across the APIs, subject to the owner account’s roles.
`Workspace.Read.All`	Workspace reads and search; Workspace mutations return `403`.
`Workspace.ReadWrite.All`	Workspace read and write operations.
`PrivateGPT.Read.All`	Only the ZylonGPT read-only allowlist for the selected gateway.
`PrivateGPT.ReadWrite.All`	ZylonGPT read and write operations for the selected gateway.

When a token has multiple scopes, their grants are combined. The effective permissions are then limited to the permissions of the account and role that owns the token. A broad scope cannot elevate its owner, and a read-only API token remains restricted even when its owner is a SuperAdmin. These scope restrictions apply to API tokens only; interactive sessions are unchanged.

When an account token request omits scopes, it defaults to Workspace.ReadWrite.All. Sending an explicit empty scopes array returns 400. Both PrivateGPT.Read.All and PrivateGPT.ReadWrite.All require gateway_id.

Read.All does not require gateway_id at creation. Without that gateway context, the token can use its other read grants but cannot call ZylonGPT. Gateway token creation accepts only PrivateGPT.Read.All and PrivateGPT.ReadWrite.All; requesting another scope returns 400. For backward compatibility, the gateway token endpoint maps an explicit empty legacy scope list to PrivateGPT.ReadWrite.All. For the ZylonGPT read-only endpoint list and read-write requirements, see the ZylonGPT API overview.

First Steps

Build with Zylon

Coding Agents

Token Management

Which token do I need?

Workspace Token