Manejo de Tokens

Para garantizar la seguridad y el rendimiento de la API, implementamos límites de velocidad (Rate Limiting) estrictos en la generación de tokens.

Importante

No generes un nuevo token para cada consulta. Debes reutilizar el mismo token hasta que esté próximo a expirar.

Ciclo de Vida del Token

Los tokens JWT de Sheriff tienen una duración de 1 hora. La estrategia correcta de integración es:

1. Generar un token y guardarlo en memoria/caché.
2. Reutilizar ese token para todas las consultas (GET /perfiles/...) durante 50-55 minutos.
3. Renovar el token usando el endpoint /refrescar-token antes de que expire.
4. Si recibes un 401 Unauthorized, generar uno nuevo automáticamente.

Límites de Velocidad (Rate Limits)

Acción	Endpoint	Límite	Propósito
Generar	POST /obtener-token	3 por hora	Obtener el token inicial.
Renovar	POST /refrescar-token	60 por minuto	Mantener la sesión viva.

¿Qué pasa si excedo el límite?

Recibirás un error 429 Too Many Requests.

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded, retry in 3600 seconds"
}

Headers de Respuesta

Cada vez que generas o usas un token, la API te informa sobre su validez en los headers:

• X-Token-Expires-In: Tiempo restante de vida del token (ej: 1h).

• Cache-Control: Instrucciones de caché estándar.

Ejemplo de flujo lógico

No necesitas una librería compleja, solo seguir esta lógica:

SI (Token existe Y Token no ha expirado) ENTONCES
    Usar Token actual
SINO SI (Token existe PERO expira en < 5 minutos) ENTONCES
    Llamar a /refresh
    Guardar nuevo Token
SINO
    Llamar a /token (Usando credenciales)
    Guardar nuevo Token
FIN SI

Hacer llamada a API con el Token

Error Handling

Rate Limit Excedido

Si excedes el límite en /obtener-token:

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded, retry in 3600 seconds"
}

Solución: Para evitar, usa /refrescar-token en lugar de /obtener-token cuando renueves el token.

Token Expirado

Si tu token expira:

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

Solución: Genera un nuevo token con tus credenciales en /obtener-token.