> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zylon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Auth

> Log in and end sessions for Workspace API access.

<Warning>
  **Upcoming release — Zylon 1.58**

  These 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](/en/v1.57/overview).
</Warning>

Use these endpoints to exchange credentials for a session and log out. For SSO login redirects (Google/Microsoft) and integration OAuth, see [OpenID & OAuth](/en/v1.58/developer-manual/build-with-zylon/workspace-api/authentication/openid).

## 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](/en/v1.58/developer-manual/build-with-zylon/workspace-api/users/user).
* Join directly to an organization through `POST /api/v1/account/organization/{orgId}/join`.

```bash theme={null}
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"]
  }'
```

<Accordion title="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. |
</Accordion>

<Accordion title="Example response">
  ```json theme={null}
  {
    "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"
  }
  ```
</Accordion>

## Log in with credentials

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

<Accordion title="Example response">
  ```json theme={null}
  "ok"
  ```
</Accordion>

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

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

<Accordion title="Example response">
  ```json theme={null}
  "ok"
  ```
</Accordion>

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

<Accordion title="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. |
</Accordion>

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

<Accordion title="Example response">
  ```json theme={null}
  {
    "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
  }
  ```
</Accordion>

### Create a token

```bash theme={null}
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"]
  }'
```

<Accordion title="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`. |
</Accordion>

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](/en/v1.58/developer-manual/get-started/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`.

<Accordion title="Example response">
  ```json theme={null}
  {
    "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"
  }
  ```
</Accordion>

<Warning>
  Copy the `token` value immediately. It is returned only once and cannot be recovered later.
</Warning>

### Delete a token

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

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

<Accordion title="Example response">
  ```json theme={null}
  "Token deleted"
  ```
</Accordion>

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.