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

# Autenticación

> Inicia y cierra sesiones para acceso a Workspace API.

Usa estos endpoints para autenticar con credenciales y cerrar sesión. Para los redireccionamientos SSO (Google/Microsoft) y OAuth de integraciones, consulta [OpenID y OAuth](/es/developer-manual/build-with-zylon/workspace-api/authentication/openid).

## Creación de cuentas

Usa `POST /api/v1/auth/register` para crear una cuenta con credenciales.

Para usar esa cuenta en Workspace, necesitas al menos un usuario de workspace:

* Crea un usuario de workspace con el account ID en [Usuarios - Crear un usuario](/es/developer-manual/build-with-zylon/workspace-api/users/user).
* Añade membresías/roles adicionales con `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="Parametros del endpoint">
  | Campo      | Tipo      | Obligatorio | Descripción                                                  |
  | ---------- | --------- | ----------- | ------------------------------------------------------------ |
  | `name`     | string    | No          | Nombre visible de la cuenta.                                 |
  | `email`    | string    | Sí          | Email de la cuenta.                                          |
  | `password` | string    | Sí          | Contraseña de credenciales.                                  |
  | `roles`    | string\[] | Sí          | Roles a nivel de cuenta. Se requiere al menos un rol válido. |
</Accordion>

<Accordion title="Ejemplo de respuesta">
  ```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>

## Iniciar sesión con credenciales

```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="Ejemplo de respuesta">
  ```json theme={null}
  "ok"
  ```
</Accordion>

Un inicio de sesión correcto crea una sesión de cuenta. Cuando LDAP está habilitado, el servidor intenta primero autenticación LDAP y después usa credenciales locales como fallback.

## Cerrar sesión

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

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  "ok"
  ```
</Accordion>

## Gestionar tokens de API

Usa estos endpoints para gestionar tokens de API de la cuenta autenticada. El secreto del token solo se devuelve al crearlo; después, las respuestas de listado incluyen metadatos y el hash del token.

### Listar tokens

<Accordion title="Parametros del endpoint">
  | Parámetro de consulta | Tipo    | Obligatorio | Descripción                                                  |
  | --------------------- | ------- | ----------- | ------------------------------------------------------------ |
  | `page_size`           | integer | No          | Número máximo de tokens a devolver.                          |
  | `after` / `before`    | string  | No          | Controles de paginación por cursor cuando estén disponibles. |
  | `gateway_id`          | string  | No          | Filtra tokens por gateway ID.                                |
</Accordion>

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

<Accordion title="Ejemplo de respuesta">
  ```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>

### Crear un 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="Parametros del endpoint">
  | Campo             | Tipo      | Obligatorio | Descripción                                                                                                                           |
  | ----------------- | --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------- |
  | `name`            | string    | No          | Nombre legible del token.                                                                                                             |
  | `revoke_existing` | boolean   | No          | Si es `true`, revoca tokens existentes según la política del servidor. Por defecto es `false`.                                        |
  | `valid_until`     | timestamp | No          | Fecha de expiración. Usa `null` u omítelo si no hay expiración explícita.                                                             |
  | `scopes`          | string\[] | No          | Valores permitidos: `ReadWrite.All`, `Workspace.ReadWrite.All`, `PrivateGPT.ReadWrite.All`. Por defecto es `Workspace.ReadWrite.All`. |
  | `gateway_id`      | string    | No          | Gateway ID al crear un token asociado a un gateway.                                                                                   |
</Accordion>

<Accordion title="Ejemplo de respuesta">
  ```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>
  Copia el valor de `token` inmediatamente. Solo se devuelve una vez y no se puede recuperar después.
</Warning>

### Eliminar un token

La eliminación usa el hash almacenado del token, no el secreto en claro.

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

<Accordion title="Ejemplo de respuesta">
  ```json theme={null}
  "Token deleted"
  ```
</Accordion>

## Errores y casos límite

* **401/403**: token inválido o ausente.
* **429**: demasiados intentos de inicio de sesión.
* **400**: el registro no incluye roles de cuenta, email o contraseña obligatorios.