API Keys

O Building Block API Keys gerencia a criação, rotação, revogação e monitoramento de chaves de API para acesso programático à plataforma.

Visão Geral

As chaves de API permitem que sistemas externos se integrem à Catalisa Platform sem a necessidade de um login de usuário interativo. Cada chave está vinculada a uma Organização e a um Usuário criador, herdando as permissões disponíveis para essa associação.

Base URL

Ambiente	URL
Staging	https://api-keys.stg.catalisa.app
Produção	https://api.catalisa.app/api-keys

Endpoints

Método	Endpoint	Descrição	Permissão
POST	/api/v1/api-keys	Criar nova chave	API_KEYS_CREATE
GET	/api/v1/api-keys	Listar chaves da org	API_KEYS_READ
GET	/api/v1/api-keys/:id	Detalhes de uma chave	API_KEYS_READ
PATCH	/api/v1/api-keys/:id	Atualizar metadados	API_KEYS_UPDATE
POST	/api/v1/api-keys/:id/rotate	Rotacionar chave	API_KEYS_ROTATE
POST	/api/v1/api-keys/:id/revoke	Revogar (desativar)	API_KEYS_DELETE
DELETE	/api/v1/api-keys/:id	Excluir permanentemente	API_KEYS_DELETE
GET	/api/v1/api-keys/:id/usage	Estatísticas de uso	API_KEYS_READ_USAGE

Ciclo de Vida da Chave

1. Criação

Ao criar uma chave, o sistema gera um segredo criptográfico. O segredo completo só é exibido uma única vez no momento da criação.

curl -X POST https://api-keys.stg.catalisa.app/api/v1/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Integração CRM",
    "description": "Chave para sincronização de clientes",
    "expiresAt": "2026-12-31T23:59:59Z"
  }'

2. Rotação

A rotação gera um novo segredo para uma chave existente. Você pode definir um gracePeriod (período de carência) durante o qual o segredo antigo continuará funcionando simultaneamente ao novo, permitindo uma migração sem downtime.

3. Revogação

Revogar uma chave altera seu status para revoked, impedindo qualquer nova autenticação imediatamente, mas mantendo o histórico de uso.

Formato da Chave

As chaves geradas seguem o formato: cat_[prefixo_8_chars][segredo_32_chars]

Exemplo: cat_a1b2c3d4...

Segurança

• As chaves são armazenadas usando hashing (Argon2), o que significa que nem mesmo os administradores do sistema podem recuperar o segredo original após a criação.
• É recomendado definir uma data de expiração para todas as chaves.
• O uso de cada chave é registrado para fins de auditoria e limites de taxa.