Autenticación

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.

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.
Añade membresías/roles adicionales con 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"]
  }'

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.

Ejemplo de respuesta

{
  "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"
}

Iniciar sesión con credenciales

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

Ejemplo de respuesta

"ok"

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

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

Ejemplo de respuesta

"ok"

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

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.

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

Ejemplo de respuesta

{
  "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
}

Crear un 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"]
  }'

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.

Ejemplo de respuesta

{
  "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"
}

Copia el valor de token inmediatamente. Solo se devuelve una vez y no se puede recuperar después.

Eliminar un token

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

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

Ejemplo de respuesta

"Token deleted"

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.

Primeros pasos

Construye con Zylon

Coding Agents

Autenticación

Creación de cuentas

Iniciar sesión con credenciales

Cerrar sesión

Gestionar tokens de API

Listar tokens

Crear un token

Eliminar un token

Errores y casos límite

​Creación de cuentas

​Iniciar sesión con credenciales

​Cerrar sesión

​Gestionar tokens de API

​Listar tokens

​Crear un token

​Eliminar un token

​Errores y casos límite

Creación de cuentas

Iniciar sesión con credenciales

Cerrar sesión

Gestionar tokens de API

Listar tokens

Crear un token

Eliminar un token

Errores y casos límite