🇪🇸 EspañolAPIsAutenticación

Autenticación

Sistema de autenticación JWT para la API de Colurs.

Todos los endpoints requieren el header x-api-key para autorización.

Login / Obtener Token

Autentica un usuario y retorna tokens JWT (access y refresh).

Endpoint

POST /token/

Headers Requeridos

Content-Type: application/json
Accept: application/json
x-api-key: [API_KEY]

Request Body

CampoTipoRequeridoDescripción
usernamestring✅Email o username
passwordstring✅Contraseña
platformstring❌API, APP, PANEL, IOS, ANDROID (default: API)
codestring⚠️Código de verificación (requerido para PANEL, IOS, ANDROID)
otpstring⚠️Código 2FA de 6 dígitos (si el usuario tiene MFA habilitado)
⚠️

Importante: Para plataformas PANEL, IOS y ANDROID, se requiere un código de verificación adicional que se almacena en caché.

Ejemplo cURL

curl -X POST https://dev.backend.colurs.co/token/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-api-key: [API_KEY]" \
  -d '{
    "username": "usuario@ejemplo.com",
    "password": "Password123!",
    "platform": "API"
}'

Respuesta

response.json
{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Errores Posibles

CódigoErrorDescripción
400DataInvalidExceptionCredenciales inválidas o plataforma no válida
400CodeMustBeRequiredExceptionCódigo requerido para PANEL/IOS/ANDROID
400CodeExpiredExceptionCódigo de verificación expirado
400OTPRequiredExceptionSe requiere código 2FA (usuario tiene MFA)
400InvalidOTPExceptionCódigo 2FA inválido

Usar el Token

⚠️

El token de acceso expira en 15 minutos. Usa el refresh token para obtener uno nuevo.

Para endpoints que requieren autenticación, incluye el token en el header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Headers Completos para Requests Autenticados

Content-Type: application/json
Accept: application/json
x-api-key: [API_KEY]
Authorization: Bearer [ACCESS_TOKEN]

Renovar Token

🔄

Usa este endpoint cuando el access token expire para obtener uno nuevo sin re-autenticar.

Endpoint

POST /token/refresh/

Request

request.json
{
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Respuesta

response.json
{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
💡

El refresh token tiene una duración muy larga (10,000 días), pero es recomendable manejarlo de forma segura.

Configuración JWT

ParámetroValor
Access Token Lifetime15 minutos
Refresh Token Lifetime10,000 días
AlgoritmoHS256

Plataformas Soportadas

PlataformaDescripciónRequiere Code
APIIntegración API externa❌
APPAplicación móvil principal❌
PANELPanel administrativo web✅
IOSAplicación iOS✅
ANDROIDAplicación Android✅

Autenticación con 2FA (MFA)

Si el usuario tiene habilitada la autenticación de dos factores (campo totp_secret en el perfil), el flujo de login requiere un paso adicional.

Paso 1: Hacer login normal

Envía username, password y platform al endpoint /token/.

{
  "username": "usuario@ejemplo.com",
  "password": "Password123!",
  "platform": "API"
}

Paso 2: Recibir error OTPRequired

Si el usuario tiene 2FA habilitado, recibirás:

{
  "code_transaction": "OTPRequiredException",
  "message": "Se requiere código OTP"
}

Paso 3: Reenviar con código OTP

Envía la misma request agregando el campo otp con el código de 6 dígitos del autenticador:

{
  "username": "usuario@ejemplo.com",
  "password": "Password123!",
  "platform": "API",
  "otp": "123456"
}

Paso 4: Obtener tokens

Si el código OTP es correcto, recibirás los tokens de acceso.

{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
🔐

El código OTP se genera usando TOTP (Time-based One-Time Password) con la librería pyotp. Compatible con Google Authenticator, Authy, etc.

Autenticación para PANEL/IOS/ANDROID

Para las plataformas PANEL, IOS y ANDROID, se requiere un código de verificación adicional que se envía al usuario y se almacena temporalmente en caché.

Paso 1: Solicitar código de verificación

El usuario solicita un código que se envía a su email/teléfono.

Paso 2: Código se almacena en caché

El sistema almacena el código asociado al username del usuario.

Paso 3: Login con código

{
  "username": "usuario@ejemplo.com",
  "password": "Password123!",
  "platform": "PANEL",
  "code": "ABC123"
}

Paso 4: Validación

El sistema verifica que el código coincida con el almacenado en caché.

Logout

ℹ️

JWT es stateless. El logout se maneja eliminando los tokens en el cliente.

No existe un endpoint de logout. Para “cerrar sesión”:

  1. Elimina el access token del almacenamiento local
  2. Elimina el refresh token del almacenamiento local
  3. Redirige al usuario a la pantalla de login
⚠️

Nota de seguridad: Los tokens JWT siguen siendo válidos hasta su expiración. Si necesitas invalidar un token inmediatamente, considera implementar una lista negra de tokens en el servidor.

Permisos por Defecto

El sistema tiene configurados los siguientes permisos globales en REST_FRAMEWORK:

DEFAULT_PERMISSION_CLASSES = (
    "rest_framework_api_key.permissions.HasAPIKey",
    "rest_framework.permissions.IsAuthenticated",
)

Esto significa que, por defecto, todos los endpoints requieren:

  • ✅ API Key válida (x-api-key header)
  • ✅ Usuario autenticado (Authorization: Bearer header)

Excepciones específicas se definen en cada vista.

InicioUsuarios