Criar Chave de API

Gerar uma nova chave de API com permissões restritas para acesso programático.

POST /api/api-keys

Cria uma nova chave de API para o usuário autenticado no tenant ativo. A chave em texto plano é retornada apenas uma vez na resposta — armazene-a com segurança.

Auth: Necessária — permissão api-key:manage

Corpo da Requisição

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Rótulo legível para a chave (máximo de 255 caracteres)
`permissions`	string[]	Sim	Lista de nomes de permissões a conceder (mínimo de 1). Deve ser um subconjunto das suas permissões vigentes; `api-key:manage` não pode ser atribuída. Editável depois com `PUT /api/api-keys/:id/permissions`
`expiresAt`	string	Não	Data de expiração em formato ISO 8601. A chave é rejeitada automaticamente após essa data
`scope`	string	Sim	Escopo da chave: `project` ou `tenant` (veja abaixo)
`projectId`	UUID \| null	Condicional	Projeto ao qual a chave pertence. Obrigatório com `scope: "project"`; não é aceito com `scope: "tenant"` (`null` é aceito)

Escopo da chave

O escopo é escolhido ao criar a chave e define como a chave obtém o projeto em que trabalha:

Escopo	Chave	Projeto de cada requisição
`project`	Chave de projeto	Sempre o projeto da chave. A chave não precisa do header `x-project-id`; um header que nomeie outro projeto responde `403` nos endpoints project-scoped e project-optional
`tenant`	Chave de tenant	Qualquer projeto do tenant: declarado com o header `x-project-id` nos endpoints project-scoped, como faz um usuário. Nos endpoints project-optional o header é opcional e restringe a requisição a esse projeto

Em ambos os casos o tenant vem da chave. Veja Integração → Autenticação para o uso de cada chave.

Exemplo

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": "CI/CD Pipeline Key",
    "permissions": ["commerce:manage", "activity:view"],
    "expiresAt": "2026-12-31T23:59:59Z",
    "scope": "project",
    "projectId": "3f6c2b1a-8d4e-4f7a-9b2c-5e1d0a7f6c34"
  }'

const response = await fetch("https://api.reten.ai/api/api-keys", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "x-tenant-id": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "CI/CD Pipeline Key",
    permissions: ["commerce:manage", "activity:view"],
    expiresAt: "2026-12-31T23:59:59Z",
    scope: "project",
    projectId: "3f6c2b1a-8d4e-4f7a-9b2c-5e1d0a7f6c34",
  }),
});
const data = await response.json();
const plaintextKey = data.plaintextKey; // Armazene com segurança — retornado apenas uma vez

import requests

response = requests.post(
    "https://api.reten.ai/api/api-keys",
    headers={
        "Authorization": "Bearer <token>",
        "x-tenant-id": "<tenant-id>",
    },
    json={
        "name": "CI/CD Pipeline Key",
        "permissions": ["commerce:manage", "activity:view"],
        "expiresAt": "2026-12-31T23:59:59Z",
        "scope": "project",
        "projectId": "3f6c2b1a-8d4e-4f7a-9b2c-5e1d0a7f6c34",
    },
)
data = response.json()
plaintext_key = data["plaintextKey"]  # Armazene com segurança — retornado apenas uma vez

Resposta `201 Created`

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "name": "CI/CD Pipeline Key",
  "keyPrefix": "rtn_sk_a1b2c3d4",
  "plaintextKey": "rtn_sk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "tenantId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "projectId": "3f6c2b1a-8d4e-4f7a-9b2c-5e1d0a7f6c34",
  "isActive": true,
  "permissions": ["commerce:manage", "activity:view"],
  "expiresAt": "2026-12-31T23:59:59.000Z",
  "lastUsedAt": null,
  "createdAt": "2026-02-26T14:30:00.000Z",
  "revokedAt": null
}

O campo plaintextKey é incluído apenas na resposta de criação. Não pode ser recuperado novamente — se for perdido, revogue a chave e crie uma nova.

A resposta não inclui scope: o escopo da chave é lido de projectId — o UUID do projeto para uma chave de projeto, null para uma chave de tenant. O mesmo vale para Listar Chaves de API.

Respostas de Erro

Status	Descrição
`400`	Erro de validação — campos ausentes, array de permissões vazio ou com duplicatas, ou nomes de permissões inválidos
`400`	`scope` ausente, ou diferente de `tenant` / `project`
`400`	`scope: "project"` sem um `projectId` válido — `Una key de alcance project requiere el projectId (UUID) de un proyecto del tenant.`
`400`	`scope: "tenant"` com um `projectId` — `Una key de alcance tenant no lleva projectId.`
`401`	Token de autenticação ausente ou inválido
`403`	O conjunto solicitado inclui uma permissão que você não possui atualmente — `Cannot assign permissions you do not have: …`
`403`	O conjunto solicitado inclui `api-key:manage` — `Cannot assign api-key:manage to an API key`
`404`	`projectId` não é um projeto do tenant — `El proyecto no existe.`