Authentication

Proteja sus solicitudes API con tokens bearer JWT.

Descripción General

CyberOrigen utiliza JSON Web Tokens (JWT) para la autenticación de API. Todas las solicitudes a endpoints protegidos deben incluir un token válido.

Obtener un Token

Endpoint de Login

POST /api/v1/auth/token
Content-Type: application/x-www-form-urlencoded

username=[email protected]&password=yourpassword

Respuesta

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

Ejemplo con cURL

curl -X POST https://backend.cyberorigen.com/api/v1/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "[email protected]&password=yourpassword"

Usar Tokens

Incluya el token en el header Authorization:

curl https://backend.cyberorigen.com/api/v1/scans \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Actualizar Token

Los tokens expiran después de 1 hora. Actualice antes de la expiración:

POST /api/v1/auth/refresh
Authorization: Bearer YOUR_CURRENT_TOKEN

Respuesta:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

API Keys

Professional y Enterprise

Las API keys están disponibles en los planes Professional y Enterprise.

Para sistemas automatizados, use API keys en lugar de credenciales de usuario:

Crear una API Key

1. Vaya a Settings > API Keys
2. Haga clic en Generate New Key
3. Configure permisos y expiración
4. Copie la clave (se muestra solo una vez)

Usar API Keys

curl https://backend.cyberorigen.com/api/v1/scans \
  -H "X-API-Key: YOUR_API_KEY"

Permisos de API Key

Permiso	Descripción
read:scans	Ver resultados de escaneos
write:scans	Crear y gestionar escaneos
read:findings	Ver hallazgos de vulnerabilidades
write:findings	Actualizar estado de hallazgos
read:grc	Ver datos GRC
write:grc	Modificar controles y evidencia

MFA para Acceso API

Cuando MFA está habilitado, las solicitudes iniciales de token requieren el código MFA:

POST /api/v1/auth/token
Content-Type: application/x-www-form-urlencoded

username=[email protected]&password=yourpassword&mfa_code=123456

Gestión de Sesiones

Listar Sesiones Activas

GET /api/v1/auth/sessions

Revocar una Sesión

DELETE /api/v1/auth/sessions/{session_id}

Revocar Todas las Sesiones

POST /api/v1/auth/logout-all

Mejores Prácticas de Seguridad

1. Nunca exponga tokens en código del lado del cliente o control de versiones
2. Use API keys para sistemas automatizados en lugar de credenciales de usuario
3. Rote las API keys regularmente
4. Configure expiración apropiada para las API keys
5. Use permisos mínimos requeridos para su integración

Respuestas de Error

Credenciales Inválidas

{
  "detail": "Incorrect email or password",
  "error_code": "INVALID_CREDENTIALS"
}

Token Expirado

{
  "detail": "Token has expired",
  "error_code": "TOKEN_EXPIRED"
}

Token Inválido

{
  "detail": "Could not validate credentials",
  "error_code": "INVALID_TOKEN"
}

MFA Requerido

{
  "detail": "MFA code required",
  "error_code": "MFA_REQUIRED"
}