Autenticación API

Autentícate con la API REST de sh0 usando tokens Bearer JWT o claves API para acceso programático.

Obtener un token API

Para obtener un token JWT, envía una solicitud POST al endpoint de login con tus credenciales:

curl -X POST https://your-server:9000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

Si las credenciales son válidas, la API devuelve un token JWT e información del usuario:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfYWJjMTIzIiwiZXhwIjoxNzE...",
    "user": {
      "id": "usr_abc123",
      "email": "[email protected]",
      "name": "Admin",
      "role": "admin"
    }
  }
}

Si la autenticación de dos factores está habilitada, incluye el código TOTP:

curl -X POST https://your-server:9000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password",
    "totp_code": "123456"
  }'

Autenticación con token Bearer

Incluye el token JWT en el encabezado Authorization de cada solicitud API:

curl https://your-server:9000/api/apps \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

El token contiene el ID de usuario, rol y tiempo de expiración. sh0 valida la firma y la expiración en cada solicitud.

export SH0_TOKEN="eyJhbGciOiJIUzI1NiIs..."

curl https://your-server:9000/api/apps \
  -H "Authorization: Bearer $SH0_TOKEN"

Alternativa con clave API

Para integraciones de larga duración (pipelines CI/CD, scripts de monitoreo, webhooks), las claves API son más prácticas que los tokens JWT porque no expiran.

Crear una clave API:

1. Navega a Settings → API Keys en el panel de control.
2. Haz clic en Generate API Key.
3. Ingresa un nombre descriptivo (ej., "Pipeline CI/CD" o "Monitoreo").
4. Copia la clave inmediatamente -- se muestra solo una vez.

Usar una clave API:

curl https://your-server:9000/api/apps \
  -H "X-API-Key: sh0_key_abc123def456"

Expiración y renovación de tokens

Los tokens JWT son válidos por 30 días por defecto. El tiempo de expiración está codificado en el payload del token.

Para renovar un token por expirar, llama al endpoint de renovación con tu token actual (aún válido):

curl -X POST https://your-server:9000/api/auth/refresh \
  -H "Authorization: Bearer YOUR_CURRENT_TOKEN"

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...(new token)...",
    "expires_at": "2026-04-20T12:00:00Z"
  }
}

El panel de control renueva automáticamente los tokens antes de que expiren. Para integraciones API, implementa lógica de renovación de token o usa claves API para evitar problemas de expiración.

Tokens CSRF para solicitudes del panel

Al hacer solicitudes desde el panel de control (navegador), sh0 usa tokens CSRF para prevenir ataques de falsificación de solicitudes entre sitios. Esto se maneja automáticamente por el cliente API del panel de control.

Si estás construyendo un frontend personalizado que se autentica vía cookies (en lugar de tokens Bearer), necesitas incluir el token CSRF en tus solicitudes:

# Get a CSRF token
curl https://your-server:9000/api/auth/csrf-token \
  -H "Cookie: session=..."

# Include it in state-changing requests
curl -X POST https://your-server:9000/api/apps \
  -H "Cookie: session=..." \
  -H "X-CSRF-Token: csrf_token_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app"}'

Errores de autenticación

Cuando la autenticación falla, la API devuelve una respuesta de error estructurada:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired authentication token"
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to perform this action"
  }
}

Escenarios de error comunes: