Claves de API

Descripción general

Las claves de API ofrecen un método de autenticación alternativo para el acceso programático y entre servicios a la plataforma Reten. En lugar de usar tokens JWT obtenidos a través del flujo de login, los clientes pueden autenticarse enviando una clave de API en el header x-api-key.

Las claves de API pertenecen a un usuario y tenant específicos, y llevan un conjunto explícito de permisos elegido por su dueño — siempre un subconjunto de los permisos que el dueño tiene vigentes. El dueño puede reemplazar ese conjunto en cualquier momento con PUT /api/api-keys/:id/permissions sin rotar el secreto, y en cada solicitud los permisos efectivos de la clave son la intersección de su conjunto almacenado con los permisos vigentes del dueño. Las claves se almacenan como hashes SHA-256 — la clave en texto plano se muestra solo una vez, al momento de crearla.

Cada clave tiene además un alcance, que se elige al crearla: una clave de proyecto siempre trabaja en un proyecto, y una clave de tenant sirve para todos los proyectos del tenant y envía x-project-id donde el endpoint lo exige o para acotar una solicitud a un proyecto. Ver Alcance de la clave.

Propiedades de la clave

Autenticación con claves de API

curl -X GET https://api.reten.ai/api/commerces \
  -H "x-api-key: rtn_sk_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json"

Al usar una clave de API, el header x-tenant-id no es requerido — el tenant se resuelve automáticamente a partir del tenant asociado a la clave. En los endpoints project-scoped, una clave de tenant envía además el header x-project-id; en los endpoints project-optional el header es opcional. Una clave de proyecto siempre trabaja en su propio proyecto — ver Alcance de la clave.

Endpoints