Autenticación

Headers requeridos, permisos y métodos de autenticación para la API de integración.

Todos los endpoints de integración requieren autenticación mediante una clave de API. No se admite autenticación con JWT (token de usuario) en estos endpoints.

Header requerido

Cada solicitud debe incluir el siguiente header:

Header	Valor	Descripción
`x-api-key`	`rtn_sk_...`	Clave de API generada desde el panel de administración

curl -X GET BASE_URL/api/integration/activities/tasks \
  -H "x-api-key: YOUR_API_KEY"

No es necesario enviar el header x-tenant-id. Cada clave de API está asociada a un tenant específico y el sistema resuelve el tenant automáticamente a partir de la clave.

La clave de API se muestra una sola vez al momento de crearla. Si la pierdes, deberás revocarla y crear una nueva desde el panel de administración.

Obtener una clave de API

Ambientes de Reten

Ambiente	Panel de Admin	API Base URL
Development	app-development.reten.ai	`https://api-development.reten.ai`
Staging	app-staging.reten.ai	`https://api-staging.reten.ai`
Production	app.reten.ai	`https://api.reten.ai`

Usa la URL del panel de admin para gestionar claves de API y configuraciones de dispatch. Reemplaza BASE_URL en los ejemplos de código con la API Base URL de tu ambiente.

Las claves de API se crean desde el panel de administración de Reten por un usuario con rol ADMIN o superior:

Navega a Configuración → Claves de API
Haz clic en Crear clave de API
Asigna un nombre descriptivo (ej. "Despacho Tareas — YOM")
Selecciona los permisos necesarios según los endpoints que utilizarás
Copia la clave generada y almacénala de forma segura

Permisos por endpoint

Cada endpoint de integración requiere un permiso específico en la clave de API:

Endpoint	Método	Permiso requerido
`/api/integration/activities/tasks`	`GET`	`VIEW_ACTIVITIES`
`/api/integration/activity-results/tasks`	`POST`	`SUBMIT_ACTIVITY_RESULT`
`/api/integration/task-result-type-configs`	`GET`	`VIEW_ACTIVITIES`

Una clave de API solo puede tener permisos que sean un subconjunto de los permisos del usuario que la creó. Si necesitas un permiso adicional, contacta a un administrador del tenant.

Alcance del tenant

Cada clave de API está asociada a un único tenant. El sistema resuelve el tenant automáticamente a partir de la clave — no es necesario enviar x-tenant-id:

Si x-api-key es inválida o está revocada → respuesta 401 Unauthorized
Si la clave no tiene el permiso requerido → respuesta 403 Forbidden
Los datos retornados siempre corresponden al tenant de la clave

Token de usuario vs clave de API

Característica	JWT (Token de usuario)	API Key (Clave de API)
Uso principal	Sesiones interactivas en la app	Integraciones programáticas
Duración	15 minutos (access token)	Sin expiración (o fecha configurable)
Renovación	Automática vía refresh token	No aplica — la clave es permanente
Permisos	Todos los del rol del usuario	Subconjunto seleccionado al crear la clave
Header `x-tenant-id`	Requerido	No necesario (tenant resuelto desde la clave)
Endpoints de integración	No soportado	Requerido

Los endpoints bajo /api/integration/* solo aceptan autenticación por clave de API. Las solicitudes con JWT serán rechazadas.