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. Usa una clave de API: es el método pensado para integraciones, y los ejemplos de esta sección la usan. Los endpoints también aceptan un token de usuario (JWT) — ver Token de usuario vs clave de API.

Header requerido

Cada solicitud autenticada con una clave de API incluye 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"

Ninguna clave de API envía el header x-tenant-id: el tenant siempre sale de la clave. Que la clave envíe x-project-id depende de su alcance — una clave de proyecto no lo necesita, una clave de tenant lo envía donde el endpoint lo exige o para acotar una solicitud a un proyecto. Ver Alcance 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 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`	`activity:view`
`/api/integration/activity-results/tasks`	`POST`	`activity-result:submit`
`/api/integration/task-result-type-configs`	`GET`	`activity:view`
`/api/integration/commerces/batch-upsert`	`POST`	`commerce:batch-upsert`
`/api/integration/operators/batch-upsert`	`POST`	`operator:batch-upsert`
`/api/integration/routes/batch-upsert`	`POST`	`route:batch-upsert`

Los permisos de una clave de API los elige su dueño y deben ser un subconjunto de los permisos que el dueño tiene vigentes. En cada solicitud, los permisos efectivos de la clave son la intersección de su conjunto almacenado con los permisos vigentes del dueño — si el dueño pierde un permiso, la clave también lo pierde; si el dueño gana uno, la clave no lo gana. Si necesitas un permiso adicional, el dueño de la clave lo agrega editando los permisos de la clave con PUT /api/api-keys/:id/permissions o desde Configuración → Claves API.

Alcance de la clave

Cada clave de API pertenece a un único tenant, y el tenant siempre sale de la clave — ninguna clave envía x-tenant-id. El alcance de la clave, que se elige al crearla (ver Crear Clave de API), decide cómo se elige el proyecto en los endpoints project-scoped y project-optional.

Los endpoints project-scoped trabajan en exactamente un proyecto por solicitud. Los endpoints project-optional aceptan x-project-id pero no lo exigen: si se envía, acota la solicitud a ese proyecto y se valida igual que en un endpoint project-scoped. Sin él, una lectura abarca todo el tenant y un resultado toma el proyecto de su actividad; un resultado sin activity_id no tiene actividad de la que tomar el proyecto, así que necesita el header — sin él la API responde 400. Una clave de proyecto siempre trabaja en su propio proyecto.

	Clave de proyecto (`scope: "project"`)	Clave de tenant (`scope: "tenant"`)
Proyecto de cada solicitud	Siempre el proyecto de la clave	El que nombra `x-project-id`; en un endpoint project-optional sin el header, ninguno
`x-project-id` en endpoints project-scoped	No hace falta. Enviar el propio proyecto de la clave se acepta; nombrar otro proyecto responde `403` — `La API key pertenece a un proyecto distinto del que declara el header x-project-id.`	Obligatorio. Sin él la API responde `400` — `Falta el header obligatorio x-project-id.`
`x-project-id` en endpoints project-optional	No hace falta, igual que en los endpoints project-scoped: nombrar otro proyecto responde `403`. Un resultado sin `activity_id` va al proyecto de la clave; un resultado de una actividad de otro proyecto responde `404` — `Actividad no encontrada.`	Opcional. Con él, la solicitud se acota a ese proyecto. Sin él, una lectura abarca todo el tenant y un resultado toma el proyecto de su actividad; un resultado sin `activity_id` responde `400` — `Falta el header obligatorio x-project-id: un resultado sin activity_id necesita proyecto.`
`x-project-id` en endpoints tenant-level	Se ignora	Se ignora

Los endpoints de integración se reparten así:

Endpoint	Método	Tipo
`/api/integration/activities/tasks`	`GET`	Project-optional
`/api/integration/activity-results/tasks`	`POST`	Project-optional
`/api/integration/task-result-type-configs`	`GET`	Tenant-level
`/api/integration/commerces/batch-upsert`, `/api/integration/operators/batch-upsert`, `/api/integration/routes/batch-upsert`	`POST`	Tenant-level

Los ejemplos de la API de integración sólo envían x-api-key, así que funcionan tal cual con una clave de proyecto y con una clave de tenant. Con una clave de tenant, agrega el header x-project-id para acotar una llamada a un proyecto, y siempre para enviar un resultado sin activity_id.

Las claves de API creadas antes de que existieran los proyectos son claves de tenant (projectId: null) y siguen la columna de la clave de tenant de arriba: envían x-project-id en los endpoints project-scoped y para enviar un resultado sin activity_id.

Si tu sistema recibe actividades por dispatch, usa una clave de tenant para enviar sus resultados. El dispatch envía las actividades de todos los proyectos del tenant, y una clave de proyecto sólo alcanza a su propio proyecto: con ella, el resultado de una actividad de otro proyecto responde 404 — Actividad no encontrada.

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 y, cuando la solicitud tiene un proyecto activo (el de la clave o el de x-project-id), a ese proyecto

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	Conjunto elegido por el dueño, editable en cualquier momento; efectivos = intersección con los permisos vigentes del dueño en cada solicitud
Header `x-tenant-id`	Requerido	No necesario (tenant resuelto desde la clave)
Header `x-project-id`	Requerido en endpoints project-scoped; opcional en endpoints project-optional (ver Alcance de la clave)	Clave de proyecto: no necesario. Clave de tenant: igual que un token de usuario
Endpoints de integración	Aceptado	Recomendado

Los endpoints bajo /api/integration/* aceptan ambos métodos; usa una clave de API para las integraciones. Con un token de usuario, cada solicitud envía Authorization: Bearer <access_token> y x-tenant-id; x-project-id sigue las mismas reglas que con una clave de tenant — ver Contexto de Proyecto.