Authentication
Auth Routes

URLs Base

URL Principal: https://api.identia.cc/api
URL Secundario: https://identiapreview.multibacks.multipacha.com/api

API de Autenticación - Documentación

Todos los endpoints están bajo la ruta /auth y utilizan el formato JSON para las peticiones y respuestas.

Endpoints

1. Registro de Usuario

Registra un nuevo usuario en el sistema.

Endpoint: POST /auth/signup

Query Parameters:

verify_email (opcional): “true” o “false”. Define si se requiere verificación de email.

Request Body (Persona):

{
  "userType": "person",
  "attributes": {
    "name": "string",
    "lastname": "string",
    "nickname": "string",
    "email": "string",
    "phone": "string",
    "dni": "string"
  },
  "base": "string (alias de plataforma)",
  "otp": "string (6 caracteres, opcional)"
}

Request Body (Dispositivo):

{
  "userType": "device",
  "attributes": {
    "name": "string",
    "serial_number": "string",
    "model": "string"
  },
  "base": "string (alias de plataforma)"
}

Response (200 OK):

{
  "userId": "string (ObjectId)",
  "token": "string (JWT)"
}

Al usuario se le asignará la entidad “por defecto” que está asociada a la plataforma

Ejemplo con curl:

curl -X POST https://api.identia.cc/auth/signup?verify_email=false \
  -H "Content-Type: application/json" \
  -d '{
    "userType": "person",
    "attributes": {
      "name": "Juan",
      "lastname": "Pérez",
      "nickname": "juanp",
      "email": "juan.perez@example.com",
      "phone": "+51987654321",
      "dni": "12345678"
    },
    "base": "identia",
    "otp": "123456"
  }'

2. Inicio de Sesión

Autentica a un usuario y devuelve un token JWT.

Importante:
Si la plataforma tiene 2 o más entidades se debe realizar el 2do paso para seleccionar una.

Selección Automática: Si se provee el campo domain en la petición y el usuario tiene acceso, se devolverá automáticamente el token completo (sub, entityId, platformId).
Si la plataforma solo está asociada a una entidad, simplemente se devuelve el token completo: (sub, entityId, platformId)
Caso contrario el token solo contiene (sub, platformId)

Endpoint: POST /auth/signin

Request Body (Persona):

{
  "userType": "person",
  "base": "string (alias de plataforma)",
  "domain": "string (dominio de la entidad, opcional)",
  "areaId": "string (ObjectId, opcional)",
  "credentials": {
    "typeCredential": "nickname | email | dni",
    "credential": "string",
    "password": "string (mínimo 6 caracteres)"
  }
}

Request Body (Dispositivo):

{
  "userType": "device",
  "base": "string (alias de plataforma)",
  "domain": "string (dominio de la entidad, opcional)",
  "areaId": "string (ObjectId, opcional)",
  "credentials": {
    "typeCredential": "name",
    "credential": "string",
    "message": "string",
    "signature": "string"
  }
}

Response (200 OK):

{
  "user": {
    "id": "string (userId)",
    "userType": "string (userTypeId)",
    "attributes": {
      "name": "string",
      "lastname": "string",
      "email": "string",
      "nickname": "string",
      "dni": "string",
      // otros atributos según el tipo de usuario
    }
  },
  "platform": {
    "id": "string (platformId)",
    "platform_name": "string",
    "description": "string"
  },
  "roles": [
    "string (role slug)"
  ],
  "entities": [
    {
      "id": "string (entityId)",
      "brand_name": "string",
      "legal_name": "string",
      "domain": "string"
    }
  ],
  "token": "string (JWT token; básico si requiere selección o completo si se usó selección automática)",
  "multipleEntities": "boolean (true si tiene más de una entidad)",
  "message": "string (mensaje indicando si debe seleccionar entidad o si ya inició sesión)"
}

Response (401 Unauthorized):

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Credenciales inválidas"
}

Ejemplo con curl:

curl -X POST https://api.identia.cc/auth/signin \
  -H "Content-Type: application/json" \
  -d '{
    "userType": "person",
    "base": "identia",
    "credentials": {
      "typeCredential": "email",
      "credential": "juan.perez@example.com",
      "password": "miPassword123"
    }
  }'

2.1 Consultar Entidades Disponibles

Permite consultar las entidades disponibles por un usuario después del inicio de sesión inicial.

Importante:
Esta ruta debe usarse cuando el usuario tiene múltiples entidades disponibles (multipleEntities: true)
y necesita ver la lista completa antes de seleccionar una entidad específica.
Util después del login con Google, para saber si el usuario tiene múltiples entidades asignadas

Endpoint: GET /auth/signin/entities

Headers:

Authorization: Bearer <token> (requerido - token básico obtenido en /auth/signin)

Response (200 OK):

{
  "entities": [
    {
      "id": "string (entityId)",
      "brand_name": "string",
      "legal_name": "string",
      "domain": "string",
      "platforms": [
        {
          "id": "string (platformId)",
          "platform_name": "string"
        }
      ]
    }
  ],
  "count": "number (cantidad total de entidades)",
  "message": "string (mensaje descriptivo)"
}

Response (401 Unauthorized):

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Token básico inválido o expirado. Por favor, inicia sesión nuevamente"
}

Response (404 Not Found):

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "No se encontraron entidades para este usuario"
}

Ejemplo con curl:

curl -X GET https://api.identia.cc/auth/signin/entities \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Ejemplo de respuesta:

{
  "entities": [
    {
      "id": "507f1f77bcf86cd799439011",
      "brand_name": "Empresa ABC",
      "legal_name": "Empresa ABC S.A.",
      "domain": "empresa-abc",
      "platforms": [
        {
          "id": "507f1f77bcf86cd799439015",
          "platform_name": "Identia"
        }
      ]
    },
    {
      "id": "507f1f77bcf86cd799439012",
      "brand_name": "Empresa XYZ",
      "legal_name": "Empresa XYZ Ltda.",
      "domain": "empresa-xyz",
      "platforms": [
        {
          "id": "507f1f77bcf86cd799439015",
          "platform_name": "Identia"
        }
      ]
    }
  ],
  "count": 2,
  "message": "Entidades disponibles para selección"
}

3. Inicio de Sesión: 2do paso (Seleccionar entidad)

Permite seleccionar una entidad específica después de la autenticación inicial.

Importante:
Solo se debe realizar este paso si la plataforma está asociada a 2 o más entidades.

Si la plataforma solo está asociada a una entidad, simplemente se cargará el token completo:
(sub, entityId, platformId)

Endpoint: POST /auth/signin/entity

Headers:

Authorization: Bearer <token> (requerido)

Request Body:

{
  "entity": "string (ObjectId)"
}

Response (200 OK):

{
  "user": {
    "id": "string (userId)",
    "userType": "string (userTypeId)",
    "attributes": {
      "name": "string",
      "lastname": "string",
      "email": "string",
      "nickname": "string",
      "dni": "string",
      // otros atributos según el tipo de usuario
    }
  },
  "platform": {
    "id": "string (platformId)",
    "platform_name": "string",
    "description": "string"
  },
  "roles": [
    "string (role slug)"
  ],
  "entities": [
    {
      "id": "string (entityId)",
      "brand_name": "string",
      "legal_name": "string",
      "domain": "string"
    }
    //Siempre habrá solamente una entidad!!
  ],
  "token": "string (JWT token completo sub, entityId, platformId)",
  "multipleEntities": "boolean (false)",
  "message": "string (mensaje indicando que el usuario inició sesión correctamente)"
}

Response (401 Unauthorized):

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Token básico inválido o expirado. Por favor, inicia sesión nuevamente"
}

Ejemplo con curl:

curl -X POST https://api.identia.cc/auth/signin/entity \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "entity": "507f1f77bcf86cd799439011"
  }'

4. Inicio de Sesión de Administrador (No usar por el momento)

Inicia sesión y genera un token para administradores con acceso a áreas.

Endpoint: POST /auth/signin/admin

Request Body:

{
  "userType": "person",
  "base": "string (opcional)",
  "areaId": "string (ObjectId, opcional)",
  "credentials": {
    "typeCredential": "nickname | email | dni",
    "credential": "string",
    "password": "string"
  }
}

Response (200 OK):

{
  "token": "string (JWT)",
  "user": {
    "id": "string",
    "roles": []
  }
}

Ejemplo con curl:

curl -X POST https://api.identia.cc/auth/signin/admin \
  -H "Content-Type: application/json" \
  -d '{
    "userType": "person",
    "areaId": "507f1f77bcf86cd799439012",
    "credentials": {
      "typeCredential": "email",
      "credential": "admin@example.com",
      "password": "adminPassword123"
    }
  }'

5. Autenticación con Google

5.1 Iniciar Autenticación

Redirige al usuario a la página de autenticación de Google.

Endpoint: GET /auth/google

Query Parameters:

base (requerido): alias de la plataforma

Respuesta:
Redirige a la página de autenticación de Google.

Ejemplo:

curl -X GET "https://api.identia.cc/auth/google?base=identia"

5.2 Callback de Google

Google redirige automáticamente después de la autenticación exitosa.

Endpoint: GET /auth/google/callback

Respuesta:
Redirige a: {PLATFORM_URL}/auth/callback?token={JWT_TOKEN}

En caso de error: {PLATFORM_URL}/login?error=auth_failed

Nota Importante: La URL de redirección se obtiene del atributo url del front de la plataforma especificada en el parámetro base del paso anterior. Es fundamental que al crear una plataforma se configure correctamente su URL. (Obligatoriamente)

Si hay más de una entidad asociada a la plataforma el token recibido será el baśico, por lo cual se debe seleccionar la entidad en el endpoint:
POST /auth/signin/entity

6. Registro de Espectador

Registra un espectador (viewer) en el sistema.

Endpoint: POST /auth/register-viewer

Request Body:

{
  "name": "string",
  "nickname": "string",
  "dni": "string (opcional)",
  "entityId": "string (ObjectId)",
  "teacherId": "string (ObjectId)",
  "token": "string (opcional)"
}

Response (200 OK):

{
  "viewerId": "string",
  "status": "registered"
}

Ejemplo con curl:

curl -X POST https://api.identia.cc/auth/register-viewer \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Carlos Viewer",
    "nickname": "carlosv",
    "dni": "87654321",
    "entityId": "507f1f77bcf86cd799439011",
    "teacherId": "507f1f77bcf86cd799439015"
  }'

7. Enviar OTP

Envía un código OTP al email del usuario para verificación.

Endpoint: POST /auth/send-otp

Request Body:

{
  "email": "string (email válido)"
}

Response (200 OK):

{
  "email_send": true,
  "message": "Correo de validación enviado"
}

Ejemplo con curl:

curl -X POST https://api.identia.cc/auth/send-otp \
  -H "Content-Type: application/json" \
  -d '{
    "email": "usuario@example.com"
  }'

8. Enviar Magic Link

Envía un enlace mágico (magic link) para autenticación sin contraseña.

Endpoint: POST /auth/send-link

Request Body:

{
  "email": "string",
  "base": "string (alias de plataforma)"
}

Response (200 OK):

{
  "response": "Link enviado exitosamente"
}

Email
En el email enviado, el usuario se encontrará un link que al hacer clic redigirige a:
{PLATFORM_URL}/link/callback?token={JWT_TOKEN}

Para validar el token se debe usar el endpoint:
POST /auth/validate-link

Ejemplo con curl:

curl -X POST https://api.identia.cc/auth/send-link \
  -H "Content-Type: application/json" \
  -d '{
    "email": "usuario@example.com",
    "base": "identia"
  }'

9. Enviar Enlace de Recuperación

Envía un enlace para recuperar la contraseña.

Endpoint: POST /auth/send-recovery-password

Request Body:

{
  "email": "string",
  "url": "string (URL base para la recuperación)"
}

Response (200 OK):

{
  "response": "Enlace de recuperación enviado"
}

Email
En el email enviado, el usuario se encontrará un link que al hacer clic redigirige a:
{PLATFORM_URL}/forgot-password?token={JWT_TOKEN}

El token se debe usar en la ruta:
PATCH /auth/recovery-password

Ejemplo con curl:

curl -X POST https://api.identia.cc/auth/send-recovery-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "usuario@example.com"
  }'

10. Recuperar Contraseña

Cambia la contraseña del usuario utilizando el token de recuperación.

Endpoint: PATCH /auth/recovery-password

Query Parameters:

token (requerido): Token de recuperación recibido por email

Request Body:

{
  "password": "string (nueva contraseña)"
}

Response (200 OK):

{
  "password_changed": true
}

Ejemplo con curl:

curl -X PATCH "https://api.identia.cc/auth/recovery-password?token=abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "nuevaPassword123"
  }'

11. Validar Magic Link

Valida un magic link y autentica al usuario.

Endpoint: POST /auth/validate-link

Query Parameters:

areaId (opcional): ID del área

Request Body:

{
  "token": "string (token del magic link)"
}

Response (200 OK):

{
  "user": {
    "id": "string",
    "userType": "string",
    "attributes": {
      "name": "string",
      "lastname": "string", 
      "email": "string",
      "nickname": "string",
      "dni": "string"
      // otros atributos según el tipo de usuario
    }
  },
  "platform": {
    "id": "string",
    "platform_name": "string",
    "alias": "string", 
    "description": "string"
  },
  "roles": ["string"] | [],
  "entities": [
    {
      "id": "string",
      "brand_name": "string",
      "legal_name": "string"
    }
  ],
  "token": "string (JWT)",
  "multipleEntities": "boolean",
  "message": "string"
}

Si hay más de una entidad asociada a la plataforma el token recibido será el baśico, por lo cual se debe seleccionar la entidad en el endpoint:
POST /auth/signin/entity

Ejemplo con curl:

curl -X POST "https://api.identia.cc/auth/validate-link?areaId=507f1f77bcf86cd799439012" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "magicLinkToken123"
  }'

12. Validar Email

Valida el email del usuario utilizando el código OTP.

Endpoint: POST /auth/validate-email

Request Body:

{
  "email": "string",
  "otpCode": "string (código de 6 dígitos)"
}

Response (200 OK):

{
  "validated": true
}

Ejemplo con curl:

curl -X POST https://api.identia.cc/auth/validate-email \
  -H "Content-Type: application/json" \
  -d '{
    "email": "usuario@example.com",
    "otpCode": "123456"
  }'

13. Generar Token de Área

Genera un token específico para acceder a un área dentro de una entidad.

Endpoint: POST /auth/token-area

Request Body:

{
  "accessToken": "string (JWT actual)",
  "entityId": "string (ObjectId)"
}

Response (200 OK):

{
  "token": "string (JWT con contexto de área)",
  "areaId": "string"
}

Ejemplo con curl:

curl -X POST https://api.identia.cc/auth/token-area \
  -H "Content-Type: application/json" \
  -d '{
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "entityId": "507f1f77bcf86cd799439011"
  }'

14. Validar Token de Usuario

Verifica si un token JWT es válido.

Endpoint: POST /auth/validate-auth

Request Body:

{
  "token": "string (JWT)"
}

Response (200 OK):

{
  "hasAccess": true
}

Response (401 Unauthorized):

{
  "hasAccess": false
}

Ejemplo con curl:

curl -X POST https://api.identia.cc/auth/validate-auth \
  -H "Content-Type: application/json" \
  -d '{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

15. Obtener Access Token

Genera un access token para operaciones específicas de usuario.

Endpoint: GET /auth/access-token

Headers:

Authorization: Bearer <token> (requerido)

Response (200 OK):

{
  "token": "string (JWT access token)"
}

Ejemplo con curl:

curl -X GET https://api.identia.cc/auth/access-token \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Códigos de Estado HTTP

200 OK: Operación exitosa
201 Created: Recurso creado exitosamente
400 Bad Request: Datos de entrada inválidos
401 Unauthorized: Credenciales inválidas o token expirado
404 Not Found: Recurso no encontrado
409 Conflict: Conflicto (ejemplo: usuario ya existe)
500 Internal Server Error: Error del servidor

Notas de Seguridad

Todos los tokens JWT tienen un tiempo de expiración.
Las contraseñas deben tener un mínimo de 6 caracteres.
Los códigos OTP tienen una validez temporal limitada.
Los magic links expiran después de un tiempo determinado.
Se recomienda usar HTTPS en producción para todas las peticiones.
Los tokens de recuperación son de un solo uso.

Flujos de Autenticación Comunes

POST /auth/signup - Registrar usuario
POST /auth/send-otp - Enviar OTP (si verify_email=true)
POST /auth/validate-email - Validar email
POST /auth/signin - Iniciar sesión
POST /auth/signin/entity - Seleccionar entidad (si aplica)

Flujo 2: Autenticación con Google

GET /auth/google - Iniciar flujo OAuth
Google redirige a /auth/google/callback
Usuario es redirigido al frontend con token

Flujo 3: Magic Link

POST /auth/send-link - Solicitar magic link
Usuario recibe email con enlace
POST /auth/validate-link - Validar magic link y obtener token

Flujo 4: Recuperación de Contraseña

POST /auth/send-recovery-password - Solicitar recuperación
Usuario recibe email con enlace
PATCH /auth/recovery-password - Establecer nueva contraseña

Ejemplos de Respuestas de Error

Error de Validación

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "details": [
    {
      "field": "email",
      "message": "Email is required"
    }
  ]
}

Error de Autenticación

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid credentials"
}

Error de Token Expirado

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Token has expired"
}

URLs Base

API de Autenticación - Documentación

Endpoints

1. Registro de Usuario

2. Inicio de Sesión

2.1 Consultar Entidades Disponibles

3. Inicio de Sesión: 2do paso (Seleccionar entidad)

4. Inicio de Sesión de Administrador (No usar por el momento)

5. Autenticación con Google

5.1 Iniciar Autenticación

5.2 Callback de Google

6. Registro de Espectador

7. Enviar OTP

8. Enviar Magic Link

9. Enviar Enlace de Recuperación

10. Recuperar Contraseña

11. Validar Magic Link

12. Validar Email

13. Generar Token de Área

14. Validar Token de Usuario

15. Obtener Access Token

Códigos de Estado HTTP

Notas de Seguridad

Flujos de Autenticación Comunes

Flujo 1: Registro y Login Tradicional

Flujo 2: Autenticación con Google

Flujo 3: Magic Link

Flujo 4: Recuperación de Contraseña

Ejemplos de Respuestas de Error

Error de Validación

Error de Autenticación

Error de Token Expirado

On This Page