Autenticação

Todos os endpoints exigem autenticação, exceto os marcados como Públicos. A Reten suporta dois métodos de autenticação.

API Keys (Recomendado para Integrações)

As API keys fornecem autenticação sem estado, ideal para integrações, pipelines de CI/CD e comunicação entre serviços.

Características Principais

• Permissões restritas — cada key carrega uma lista explícita de permissões escolhida pelo seu dono (subconjunto das permissões vigentes do dono, editável pelo dono a qualquer momento); em cada requisição, as permissões efetivas são a interseção dessa lista com as permissões vigentes do dono
• Vinculada a um tenant — cada key está associada a um tenant específico (não é necessário o header x-tenant-id); seu escopo define se ela também fica vinculada a um projeto (veja Contexto de Projeto)
• Armazenamento seguro — apenas um hash SHA-256 é armazenado; a key em texto plano é exibida uma única vez na criação
• Expiração opcional — as keys podem ter uma data de expiração, após a qual são rejeitadas automaticamente

Criando uma API Key

Crie uma API key via POST /api/api-keys com as permissões desejadas. A key em texto plano é retornada uma única vez e deve ser armazenada com segurança.

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": ["activity:view", "activity:create"],
    "scope": "project",
    "projectId": "<project-id>"
  }'

import axios from 'axios';

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

// Guarde esta key com segurança — ela só é exibida uma vez
const apiKey = response.data.plaintextKey; // rtn_sk_...

Usando uma API Key

Inclua a key no header x-api-key em todas as requisições:

x-api-key: rtn_sk_<key>

Ao usar uma API key, o tenant é resolvido a partir da key — não é necessário o header x-tenant-id. Se a key também envia x-project-id depende do seu escopo — veja Contexto de Projeto.

Email + Senha (JWT)

Os tokens JWT são usados para sessões interativas de usuário. O fluxo envolve uma requisição de login que retorna um access token e define um cookie de refresh token.

Fluxo de Autenticação

1. Chame POST /api/auth/login com email e senha
2. Receba um access token no corpo da resposta; um refresh token é definido como cookie HTTP-only
3. Inclua o access token em todas as requisições subsequentes via o header Authorization
4. Quando o access token expirar (15 min), chame POST /api/auth/refresh — o servidor valida o cookie de refresh e emite um novo access token
5. Ao fazer logout, o cookie de refresh é limpo

Tempo de Vida dos 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",
    "username": "jdoe",
    "email": "jdoe@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "roles": ["viewer"],
    "permissions": [
      "project:view",
      "user:view",
      "activity:view",
      "commerce-lifecycle-snapshot:view"
    ],
    "tenantIds": ["660e8400-e29b-41d4-a716-446655440000"]
  }
}

Usando JWT com Contexto de Tenant

Ao autenticar com JWT, a maioria dos endpoints exige um contexto de tenant via o header x-tenant-id:

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

Você pode obter a lista de tenants aos quais seu usuário pertence via GET /api/tenant/mine.

Os endpoints project-scoped também precisam do header x-project-id, e os endpoints project-optional o aceitam — veja Contexto de Projeto.

Contexto de Projeto

Os dados de um tenant são divididos em projetos. Os endpoints project-scoped trabalham em exatamente um projeto por requisição: o projeto ativo. Os endpoints tenant-level não olham o projeto.

Os endpoints project-optional aceitam x-project-id, mas não o exigem. Se for enviado, restringe a requisição a esse projeto e é validado como em um endpoint project-scoped. Sem ele, uma leitura abrange todo o tenant e um resultado assume o projeto da sua atividade; um resultado sem activity_id não tem atividade da qual assumir o projeto, então precisa do header — sem ele a API responde 400. Uma chave de projeto sempre trabalha no seu próprio projeto: não precisa do header, e um resultado sem activity_id vai para o projeto da chave.

O projeto ativo vem de:

Envie o header junto com x-tenant-id. Os IDs de projeto são obtidos com GET /api/projects:

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

Os endpoints tenant-level ignoram o header: enviá-lo ou não, não muda a resposta. Com uma chave de API o tenant continua vindo da chave; apenas o projeto depende do escopo da chave — veja Integração → Autenticação.

Endpoints project-scoped, project-optional e tenant-level

GET /api/activity-results/tasks/sync é tenant-level: ignora x-project-id e retorna os resultados de todos os projetos do tenant.

Erros de projeto

Em um endpoint project-scoped, e em um endpoint project-optional que recebe o header, a API valida o projeto antes das permissões e do corpo da requisição. A exceção é o 400 de um resultado sem activity_id em um endpoint project-optional, que chega depois da validação do corpo da requisição: