Autenticación JWT y Límites de Tasa

La API REST de Matias Impulso (https://api.matiasimpulso.com) utiliza JSON Web Tokens (JWT) firmados para autenticar peticiones de usuarios e integraciones autorizadas.

1. Obtención y Renovación de Tokens

Operación	Endpoint	Descripción
Iniciar sesión	`POST /auth/login`	Valida credenciales y emite `token` (Access Token de vida corta) + cookie `jrt` (`HttpOnly`, `Secure`, `SameSite`) para renovación segura.
Renovar sesión	`POST /auth/refresh_token`	Emite un nuevo par de tokens rotando el refresh token activo sin solicitar contraseña nuevamente.
Consultar identidad	`GET /auth/me`	Devuelve el usuario autenticado, su rol (`admin` / `user`) y los metadatos de su `companyId`.
Cerrar sesión	`DELETE /auth/logout`	Revoca la sesión activa y limpia la cookie de refresco.

Envío del Token en Peticiones REST

Incluye siempre la cabecera Authorization: Bearer <YOUR_JWT_ACCESS_TOKEN>:

curl -X GET "https://api.matiasimpulso.com/tickets?pageNumber=1" \
  -H "Authorization: Bearer <YOUR_JWT_ACCESS_TOKEN>" \
  -H "Accept: application/json"

const res = await fetch('https://api.matiasimpulso.com/contacts?searchParam=Gomez', {
  headers: {
    Authorization: 'Bearer <YOUR_JWT_ACCESS_TOKEN>',
    Accept: 'application/json',
  },
});

if (res.status === 429) {
  const retryAfterSec = Number(res.headers.get('Retry-After') ?? '5');
  console.warn(`Límite de tasa alcanzado. Reintentar en ${retryAfterSec}s`);
}

const payload = await res.json();

import requests

headers = {
    "Authorization": "Bearer <YOUR_JWT_ACCESS_TOKEN>",
    "Accept": "application/json",
}
response = requests.get(
    "https://api.matiasimpulso.com/ai-credits/balance",
    headers=headers,
    timeout=15,
)
response.raise_for_status()
print(response.json())

2. Políticas de Rate Limiting (Protección contra Abuso)

Para garantizar baja latencia a todas las empresas en la nube, waback aplica tres ventanas simultáneas por origen/cliente:

Ventana	Límite Máximo	Cabeceras Expuestas
Ráfaga corta (`short`)	`10 peticiones / 1 segundo`	`X-RateLimit-Limit-short`, `X-RateLimit-Remaining-short`
Sostenida media (`medium`)	`50 peticiones / 10 segundos`	`X-RateLimit-Limit-medium`, `X-RateLimit-Remaining-medium`
Por minuto (`long`)	`100 peticiones / 60 segundos`	`X-RateLimit-Limit-long`, `X-RateLimit-Remaining-long`, `Retry-After`

3. Convención de Códigos HTTP

200 OK / 201 Created: operación procesada exitosamente.
400 Bad Request: error de validación en el DTO enviado (la respuesta detalla los campos rechazados).
401 Unauthorized: token ausente, expirado o revocado (ejecuta POST /auth/refresh_token).
403 Forbidden: rol insuficiente (requiere administrador del tenant o verificación de correo empresarial).
404 Not Found: recurso inexistente o perteneciente a otro companyId.
409 Conflict: duplicidad de recurso o cupo máximo del plan alcanzado.
429 Too Many Requests: límite de tasa superado; aplica exponential backoff respetando la cabecera Retry-After.