API de Autenticación

La API de Autenticación te permite obtener los tokens necesarios para acceder a la plataforma Nilo. Este endpoint es esencial para comenzar a utilizar cualquier otro servicio de la API.

Entendiendo la Autenticación

La autenticación en Nilo utiliza un enfoque de dos factores para garantizar un acceso seguro a la plataforma:

• API Key: Una clave estática que identifica tu aplicación

  • Requerida para todas las solicitudes de la API
  • Se envía en el encabezado x-api-key
  • Única por entorno (sandbox, desarrollo, producción)
  • Nunca expira a menos que sea revocada explícitamente

• Token de Acceso: Un token dinámico que autoriza tus solicitudes

  • Generado usando tus credenciales de cliente
  • Tiene un tiempo de vida limitado
  • Se envía en el encabezado Authorization
  • Contiene permisos e información del usuario codificados

Consideraciones Importantes

1. Ciclo de Vida del Token: Los tokens de acceso expiran después de un tiempo determinado y necesitan ser renovados
2. Seguridad: Nunca compartas tus claves de API o credenciales de cliente
3. Permisos: Diferentes operaciones requieren diferentes alcances de permisos
4. Límites de Tasa: Las solicitudes de autenticación pueden estar limitadas por tasa
5. Separación de Entornos: Se requieren diferentes credenciales para cada entorno

Flujo de Autenticación

1. Obtener tu API key, client ID y client secret
2. Realizar una solicitud de login para obtener un token de acceso
3. Incluir tanto la API key como el token de acceso en las solicitudes subsiguientes
4. Renovar el token de acceso antes de que expire

Obtener Token

POST /login

Este endpoint se utiliza para obtener un token de autenticación que te permitirá acceder a la API. El token obtenido debe ser incluido en el encabezado Authorization de las siguientes solicitudes.

Parámetros del Cuerpo de la Solicitud

Parámetro	Tipo	Requerido	Descripción
clientId	string	Sí	ID del cliente
clientSecret	string	Sí	Clave secreta de autenticación

Ejemplo del Cuerpo de la Solicitud

{
  "clientId": "tu-client-id",
  "clientSecret": "tu-clave-secreta"
}

Códigos de Respuesta

Código	Descripción
200	Operación exitosa - Token generado correctamente
401	No autorizado - Credenciales inválidas

Ejemplo de Uso

Javascript

const headers = {
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  clientId: "tu-client-id",
  clientSecret: "tu-clave-secreta",
};

fetch("https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/login", {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data),
})
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Python

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/login"

headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    "clientId": "tu-client-id",
    "clientSecret": "tu-clave-secreta"
}

response = requests.post(url, headers=headers, json=data)
print(response.text)

Probar el Endpoint

Test the authentication endpoint

API Key:

Client ID:

Secret:

Response:

Ejemplo de Respuesta Exitosa

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

Ejemplo de Respuesta de Error

Credenciales Inválidas

{
  "code": 401,
  "message": "Credenciales de cliente inválidas"
}

Límite de Tasa Excedido

{
  "code": 429,
  "message": "Demasiadas solicitudes",
  "retry_after": 60
}

Token Expirado

{
  "code": 401,
  "message": "El token ha expirado",
  "error_code": "TOKEN_EXPIRED"
}

Mejores Prácticas

1. Gestión de Tokens

   • Almacenar tokens de forma segura
   • Implementar renovación de tokens antes de su expiración
   • Nunca almacenar tokens en código del lado del cliente
   • Usar variables de entorno para las credenciales

2. Manejo de Errores

   • Implementar manejo adecuado de errores de autenticación
   • Agregar lógica de reintentos con retroceso exponencial
   • Monitorear la expiración de tokens
   • Registrar errores de autenticación para depuración

3. Medidas de Seguridad

   • Usar HTTPS para todas las solicitudes
   • Rotar credenciales periódicamente
   • Implementar firma de solicitudes cuando sea necesario
   • Monitorear patrones inusuales de autenticación

4. Optimización de Rendimiento

   • Almacenar tokens en caché hasta cerca de su expiración
   • Implementar renovación de tokens en procesos en segundo plano
   • Usar agrupación de conexiones para solicitudes de autenticación
   • Agrupar operaciones para minimizar la sobrecarga de autenticación

Casos de Uso Comunes

1. Configuración Inicial

   • Generar credenciales de API
   • Implementar flujo de autenticación
   • Configurar almacenamiento seguro de credenciales
   • Configurar ajustes específicos del entorno

2. Despliegue en Producción

   • Migrar de credenciales de sandbox a producción
   • Implementar medidas de seguridad adecuadas
   • Configurar monitoreo y alertas
   • Configurar métodos de autenticación de respaldo

3. Gestión Multi-Entorno

   • Gestionar diferentes credenciales por entorno
   • Implementar configuraciones específicas por entorno
   • Establecer programas de rotación de credenciales
   • Configurar mecanismos de failover

4. Resolución de Problemas

   • Monitorear fallos de autenticación
   • Depurar problemas de expiración de tokens
   • Rastrear problemas de límites de tasa
   • Analizar incidentes de seguridad

Tipos de Respuesta

Respuesta Exitosa

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

Ejemplos de Respuesta de Error

Credenciales Inválidas

{
  "code": 401,
  "message": "Invalid client credentials"
}

Límite de Tasa Excedido

{
  "code": 429,
  "message": "Too many requests"
}

Token Expirado

{
  "code": 401,
  "message": "Unauthorized"
}

Recomendaciones de Seguridad

1. Almacenamiento de Credenciales

   • Usar bóvedas seguras de credenciales
   • Encriptar datos sensibles en reposo
   • Implementar controles de acceso
   • Auditorías regulares de seguridad

2. Seguridad en las Solicitudes

   • Validar certificados SSL
   • Implementar firma de solicitudes
   • Usar canales de comunicación seguros
   • Monitorear brechas de seguridad

3. Control de Acceso

   • Implementar acceso basado en roles
   • Auditorías regulares de permisos
   • Monitorear actividad inusual
   • Implementar lista blanca de IPs

4. Cumplimiento

   • Seguir mejores prácticas de seguridad
   • Implementar registro de auditoría
   • Revisiones regulares de seguridad
   • Mantener documentación de cumplimiento

Uso del Token

El token obtenido debe ser incluido en todas las solicitudes subsiguientes como un encabezado de autorización:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Seguridad

Todos los endpoints de la API requieren dos tipos de autenticación:

1. Clave API en el encabezado: x-api-key
2. Token de autorización en el encabezado: Authorization

Tiempo de Expiración

El token tiene un tiempo de vida limitado, especificado en el campo expiresIn de la respuesta (en segundos). Deberás solicitar un nuevo token una vez que el actual haya expirado.