Autenticación

Todos los endpoints requieren autenticación a menos que estén marcados como Públicos. Reten soporta dos métodos de autenticación.

API Keys (Recomendado para Integraciones)

Las API keys proporcionan autenticación sin estado, ideal para integraciones, pipelines CI/CD y comunicación entre servicios.

Características Principales

• Permisos acotados — cada key tiene una lista explícita de permisos (subconjunto de los del creador)
• Vinculada a un tenant — cada key está asociada a un tenant específico (no se necesita el header x-tenant-id)
• Almacenamiento seguro — solo se almacena un hash SHA-256; la key en texto plano se muestra una sola vez al crearla
• Expiración opcional — las keys pueden tener una fecha de expiración tras la cual se rechazan automáticamente

Crear una API Key

Crea una API key vía POST /api/api-keys con los permisos deseados. La key en texto plano se devuelve una sola vez y debe almacenarse de forma segura.

curl -X POST https://api.reten.ai/api/api-keys \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Integration Key",
    "permissions": ["VIEW_ACTIVITIES", "CREATE_ACTIVITY"]
  }'

import axios from 'axios';

const response = await axios.post(
  'https://api.reten.ai/api/api-keys',
  {
    name: 'Integration Key',
    permissions: ['VIEW_ACTIVITIES', 'CREATE_ACTIVITY'],
  },
  {
    headers: {
      Authorization: 'Bearer <token>',
      'x-tenant-id': '<tenant-id>',
    },
  }
);

// Guarda esta key de forma segura — solo se muestra una vez
const apiKey = response.data.key; // rtn_sk_...

Usar una API Key

Incluye la key en el header x-api-key en todas las solicitudes:

x-api-key: rtn_sk_<key>

Al usar una API key, el tenant se resuelve automáticamente — no se necesita el header x-tenant-id.

Email + Contraseña (JWT)

Los tokens JWT se usan para sesiones interactivas de usuario. El flujo implica una solicitud de login que devuelve un access token y establece un refresh token como cookie.

Flujo de Autenticación

1. Llama a POST /api/auth/login con email y contraseña
2. Recibe un access token en el cuerpo de la respuesta; un refresh token se establece como cookie HTTP-only
3. Incluye el access token en todas las solicitudes posteriores vía el header Authorization
4. Cuando el access token expire (15 min), llama a POST /api/auth/refresh — el servidor valida la cookie de refresh y emite un nuevo access token
5. Al cerrar sesión, se limpia la cookie de refresh

Tiempo de Vida de Tokens

curl -X POST https://api.reten.ai/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "admin@example.com",
    "password": "SecurePass123!"
  }'

import axios from 'axios';

const response = await axios.post(
  'https://api.reten.ai/api/auth/login',
  {
    identifier: 'admin@example.com',
    password: 'SecurePass123!',
  }
);

const { accessToken, user } = response.data;

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "admin@example.com",
    "firstName": "Admin",
    "lastName": "User"
  }
}

Usar JWT con Contexto de Tenant

Al autenticar con JWT, la mayoría de los endpoints requieren un contexto de tenant vía el header x-tenant-id:

Authorization: Bearer <access_token>
x-tenant-id: <tenant_uuid>

Puedes obtener la lista de tenants a los que pertenece tu usuario vía GET /api/tenants/my-tenants.