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

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

<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",
    "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"
  }
  ```
</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: `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.                                                                               |
</Accordion>

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