Auth

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 these endpoints to exchange credentials for a session and log out. For SSO login redirects (Google/Microsoft) and integration OAuth, see OpenID & OAuth.

Account creation

Use POST /api/v1/auth/register to create a new credentials-based account. To use that account in Workspace, complete one of these operations:

Create a workspace member with the account ID in Workspace members - Create a workspace member.
Join directly to an organization through POST /api/v1/account/organization/{orgId}/join.

curl -X POST "https://{BASE_URL}/api/v1/auth/register" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sasha Patel",
    "email": "sasha@example.com",
    "password": "{password}",
    "roles": ["Workspace"]
  }'

Endpoint parameters

Field	Type	Required	Description
`name`	string	No	Account display name.
`email`	string	Yes	Account email.
`password`	string	Yes	Credentials password.
`roles`	string[]	Yes	Account-level roles. At least one valid role is required.

Example response

{
  "id": "acct_6c8a1f3b2d4e5f7a",
  "state": "Active",
  "email": "sasha@example.com",
  "name": "Sasha Patel",
  "provider": "Credentials",
  "roles": ["Workspace"],
  "created_at": "2026-02-08T14:12:45Z",
  "updated_at": "2026-02-08T14:12:45Z"
}

Log in with credentials

curl -X POST "https://{BASE_URL}/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "{username}",
    "password": "{password}"
  }'

Example response

"ok"

Successful login creates an account session. When LDAP is enabled, the server first tries LDAP authentication and then falls back to local credentials.

Log out

curl -X POST "https://{BASE_URL}/api/v1/auth/logout" \
  -H "Authorization: Bearer {API_TOKEN}"

Example response

"ok"

Manage API tokens

Use these endpoints to manage API tokens for the authenticated account. Token secrets are returned only when a token is created; after that, list responses include metadata and the token hash.

List tokens

Endpoint parameters

Query parameter	Type	Required	Description
`page_size`	integer	No	Maximum number of tokens to return.
`after` / `before`	string	No	Cursor pagination controls when available.
`gateway_id`	string	No	Filter tokens by gateway ID.

curl "https://{BASE_URL}/api/v1/account/token?page_size=20" \
  -H "Authorization: Bearer {API_TOKEN}"

Example response

{
  "data": [
    {
      "id": "tok_7f1a9c2d4b6e",
      "name": "workspace-sync",
      "token": null,
      "scopes": ["Workspace.ReadWrite.All"],
      "gateway_id": null,
      "hashed_token": "{token_hash}",
      "token_email": "workspace-sync@example.com",
      "last_used_at": "2026-05-10T08:31:12Z",
      "created_at": "2026-05-01T10:00:00Z",
      "valid_until": "2026-12-31T23:59:59Z"
    }
  ],
  "next_cursor": null,
  "previous_cursor": null,
  "has_next_page": false,
  "has_previous_page": false,
  "total_count": 1
}

Create a token

curl -X POST "https://{BASE_URL}/api/v1/account/token" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "workspace-sync",
    "revoke_existing": false,
    "valid_until": "2026-12-31T23:59:59Z",
    "scopes": ["Workspace.ReadWrite.All"]
  }'

Endpoint parameters

Field	Type	Required	Description
`name`	string	No	Human-readable token name.
`revoke_existing`	boolean	No	When `true`, revokes existing tokens according to server policy. Defaults to `false`.
`valid_until`	timestamp	No	Expiration timestamp. Use `null` or omit for no explicit expiration.
`scopes`	string[]	No	Allowed values: `Read.All`, `ReadWrite.All`, `Workspace.Read.All`, `Workspace.ReadWrite.All`, `PrivateGPT.Read.All`, and `PrivateGPT.ReadWrite.All`. If omitted, defaults to `Workspace.ReadWrite.All`; an explicit empty array returns `400`.
`gateway_id`	string	No	Required when `scopes` includes `PrivateGPT.Read.All` or `PrivateGPT.ReadWrite.All`.

Scopes on the same token are combined, then intersected with the owner account’s role permissions. A token cannot elevate its owner, including a SuperAdmin token. Scope restrictions apply to API tokens only and do not change interactive sessions. See Token Management for the access provided by each scope. Read.All can be created without gateway_id, but its ZylonGPT read grants are usable only when the token carries that gateway context. In contrast, account-token creation returns 400 when either dedicated PrivateGPT.* scope is requested without gateway_id.

Example response

{
  "id": "tok_7f1a9c2d4b6e",
  "name": "workspace-sync",
  "token": "{API_TOKEN}",
  "scopes": ["Workspace.ReadWrite.All"],
  "gateway_id": null,
  "hashed_token": "{token_hash}",
  "token_email": "workspace-sync@example.com",
  "last_used_at": null,
  "created_at": "2026-05-01T10:00:00Z",
  "valid_until": "2026-12-31T23:59:59Z"
}

Copy the token value immediately. It is returned only once and cannot be recovered later.

Delete a token

Delete uses the stored token hash, not the clear token secret.

curl -X DELETE "https://{BASE_URL}/api/v1/account/token/{token_hash}" \
  -H "Authorization: Bearer {API_TOKEN}"

Example response

"Token deleted"

Errors and edge cases

401/403: missing or invalid API token.
400: scopes is explicitly empty, a PrivateGPT scope has no gateway_id, or a gateway token request contains a non-PrivateGPT scope.
429: too many login attempts.
400: register payload missing required account roles, email, or password.

First Steps

Build with Zylon

Coding Agents

Account creation

Log in with credentials

Log out

Manage API tokens

List tokens

Create a token

Delete a token

Errors and edge cases

​Account creation

​Log in with credentials

​Log out

​Manage API tokens

​List tokens

​Create a token

​Delete a token

​Errors and edge cases

Account creation

Log in with credentials

Log out

Manage API tokens

List tokens

Create a token

Delete a token

Errors and edge cases