Chaves de API
Endpoints da API para gerenciar chaves de API para acesso programático.
Visão Geral
As chaves de API oferecem um método de autenticação alternativo para acesso programático e serviço-a-serviço à plataforma Reten. Em vez de usar tokens JWT obtidos através do fluxo de login, os clientes podem se autenticar enviando uma chave de API no header x-api-key.
As chaves de API pertencem a um usuário e tenant específicos, e carregam um conjunto explícito de permissões escolhido pelo seu dono — sempre um subconjunto das permissões que o dono possui atualmente. O dono pode substituir esse conjunto a qualquer momento com PUT /api/api-keys/:id/permissions sem rotacionar o segredo, e em cada requisição as permissões efetivas da chave são a interseção do seu conjunto armazenado com as permissões vigentes do dono. As chaves são armazenadas como hashes SHA-256 — a chave em texto plano é exibida apenas uma vez, no momento da criação.
Cada chave também tem um escopo, escolhido ao criá-la: uma chave de projeto sempre trabalha em um projeto, e uma chave de tenant serve para todos os projetos do tenant e envia x-project-id onde o endpoint o exige ou para restringir uma requisição a um projeto. Veja Escopo da chave.
Propriedades da Chave
| Propriedade | Descrição |
|---|---|
name | Rótulo legível para identificar a chave |
keyPrefix | Prefixo de exibição (ex.: rtn_sk_a1b2c3d4) para identificação sem expor a chave completa |
permissions | Lista explícita de permissões concedidas a esta chave |
projectId | O projeto da chave (string, um UUID), ou null para uma chave de tenant |
expiresAt | Data de expiração opcional, após a qual a chave é rejeitada |
lastUsedAt | Carimbo de data/hora da última autenticação bem-sucedida com esta chave |
Autenticação com chaves de API
curl -X GET https://api.reten.ai/api/commerces \
-H "x-api-key: rtn_sk_a1b2c3d4e5f6..." \
-H "Content-Type: application/json"Ao usar uma chave de API, o header x-tenant-id não é necessário — o tenant é resolvido automaticamente a partir do tenant associado à chave. Nos endpoints project-scoped, uma chave de tenant envia também o header x-project-id; nos endpoints project-optional o header é opcional. Uma chave de projeto sempre trabalha no seu próprio projeto — veja Escopo da chave.
Endpoints
Criar Chave de API
Gere uma nova chave de API com permissões restritas.
Listar Chaves de API
Liste todas as chaves de API do usuário e tenant atuais.
Atualizar Permissões da Chave de API
Substitua o conjunto de permissões de uma chave de API sem alterar o seu segredo.
Revogar Chave de API
Revogue uma chave de API ativa.