Auth - Zylon

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 user with the account ID in Users - Create a user.
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": ["Admin"]
  }'

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",
  "given_name": null,
  "family_name": null,
  "profile_picture": null,
  "provider": "Credentials",
  "users": null,
  "roles": ["Admin"],
  "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: `ReadWrite.All`, `Workspace.ReadWrite.All`, `PrivateGPT.ReadWrite.All`. Defaults to `Workspace.ReadWrite.All`.
`gateway_id`	string	No	Gateway ID when creating a gateway-scoped token.

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.
429: too many login attempts.
400: register payload missing required account roles, email, or password.

​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