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 miembro del espacio de trabajo:

Crea un miembro del espacio de trabajo con el ID de la cuenta en Miembros del espacio de trabajo - Crear un miembro del espacio de trabajo.
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": ["Workspace"]
  }'

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",
  "provider": "Credentials",
  "roles": ["Workspace"],
  "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: `Read.All`, `ReadWrite.All`, `Workspace.Read.All`, `Workspace.ReadWrite.All`, `PrivateGPT.Read.All` y `PrivateGPT.ReadWrite.All`. Si se omite, usa `Workspace.ReadWrite.All` por defecto; un array vacío explícito devuelve `400`.
`gateway_id`	string	No	Obligatorio si `scopes` incluye `PrivateGPT.Read.All` o `PrivateGPT.ReadWrite.All`.

Los scopes de un mismo token se combinan y después se intersectan con los permisos de rol de la cuenta propietaria. Un token no puede elevar a su propietario, incluidos los tokens de SuperAdmin. Las restricciones de scope solo se aplican a tokens de API y no cambian las sesiones interactivas. Consulta Gestión de tokens para ver el acceso de cada scope. Read.All puede crearse sin gateway_id, pero sus permisos de lectura de ZylonGPT solo se pueden usar cuando el token incluye ese contexto de gateway. En cambio, la creación de tokens de cuenta devuelve 400 si se solicita cualquiera de los scopes PrivateGPT.* dedicados sin gateway_id.

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.
400: scopes está vacío de forma explícita, falta gateway_id para un scope de PrivateGPT o una solicitud de token de gateway incluye un scope que no es de PrivateGPT.
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