Chaves de API

Gerenciamento completo de chaves de API para acesso programático à plataforma.

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	API_KEYS_READ
GET	/api/v1/api-keys/:id	Obter chave por ID	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 chave	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

---

Criar Chave

POST /api/v1/api-keys

Cria uma nova chave de API. O segredo completo (key) só é retornado uma única vez nesta resposta.

Request

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome da chave (1-100 caracteres)
description	string	Não	Descrição (até 500 caracteres)
expiresAt	datetime	Não	Data de expiração (ISO 8601)

cURL

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

JavaScript

const response = await fetch('https://api-keys.stg.catalisa.app/api/v1/api-keys', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Integração CRM',
    description: 'Chave para sincronização de clientes',
    expiresAt: '2026-12-31T23:59:59Z',
  }),
});

const result = await response.json();
// IMPORTANTE: Guarde o valor de 'key' - ele não será exibido novamente!
console.log('Chave:', result.key);
console.log('ID:', result.data.id);

Response (201 Created)

{
  "data": {
    "type": "api-key",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "links": {
      "self": "/api/v1/api-keys/550e8400-e29b-41d4-a716-446655440000"
    },
    "attributes": {
      "name": "Integração CRM",
      "description": "Chave para sincronização de clientes",
      "prefix": "sk_a1b2c3d4",
      "status": "ACTIVE",
      "expiresAt": "2026-12-31T23:59:59Z",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  },
  "key": "sk_a1b2c3d4.segredo_completo_aqui"
}

Atenção

O campo key só é retornado uma única vez no momento da criação. Armazene-o em local seguro imediatamente.

---

Listar Chaves

GET /api/v1/api-keys

Lista todas as chaves da organização com suporte a paginação.

Query Parameters

Parâmetro	Tipo	Descrição
page	integer	Número da página
pageSize	integer	Itens por página

cURL

curl 'https://api-keys.stg.catalisa.app/api/v1/api-keys' \
  -H 'Authorization: Bearer SEU_TOKEN'

JavaScript

const response = await fetch('https://api-keys.stg.catalisa.app/api/v1/api-keys', {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data, meta } = await response.json();
console.log(`Total de chaves: ${meta.totalItems}`);
data.forEach(key => {
  console.log(`${key.attributes.name} (${key.attributes.status})`);
});

Response (200 OK)

{
  "data": [
    {
      "type": "api-key",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "attributes": {
        "name": "Integração CRM",
        "prefix": "sk_a1b2c3d4",
        "status": "ACTIVE",
        "expiresAt": "2026-12-31T23:59:59Z",
        "lastUsedAt": "2024-01-15T14:00:00Z",
        "createdAt": "2024-01-15T10:30:00Z"
      }
    }
  ],
  "meta": {
    "totalItems": 1,
    "totalPages": 1,
    "currentPage": 1,
    "itemsPerPage": 20
  }
}

---

Obter Chave por ID

GET /api/v1/api-keys/:id

Obtém os detalhes de uma chave específica.

cURL

curl 'https://api-keys.stg.catalisa.app/api/v1/api-keys/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer SEU_TOKEN'

JavaScript

const keyId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://api-keys.stg.catalisa.app/api/v1/api-keys/${keyId}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(`Nome: ${data.attributes.name}`);
console.log(`Status: ${data.attributes.status}`);
console.log(`Prefixo: ${data.attributes.prefix}`);

---

Atualizar Chave

PATCH /api/v1/api-keys/:id

Atualiza os metadados de uma chave existente.

Request

Campo	Tipo	Descrição
name	string	Novo nome (1-100 caracteres)
description	string | null	Nova descrição

cURL

curl -X PATCH 'https://api-keys.stg.catalisa.app/api/v1/api-keys/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Integração CRM v2",
    "description": "Chave atualizada para nova versão do CRM"
  }'

JavaScript

const keyId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://api-keys.stg.catalisa.app/api/v1/api-keys/${keyId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Integração CRM v2',
    description: 'Chave atualizada para nova versão do CRM',
  }),
});

const { data } = await response.json();
console.log(`Nome atualizado: ${data.attributes.name}`);

---

Rotacionar Chave

POST /api/v1/api-keys/:id/rotate

Gera um novo segredo para a chave. O segredo antigo continua válido durante o período de carência (gracePeriodHours), permitindo migração sem downtime.

Request

Campo	Tipo	Padrão	Descrição
gracePeriodHours	number	24	Período de carência em horas (1-168)

cURL

curl -X POST 'https://api-keys.stg.catalisa.app/api/v1/api-keys/550e8400-e29b-41d4-a716-446655440000/rotate' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "gracePeriodHours": 48
  }'

JavaScript

const keyId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://api-keys.stg.catalisa.app/api/v1/api-keys/${keyId}/rotate`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    gracePeriodHours: 48,
  }),
});

const result = await response.json();
// IMPORTANTE: Guarde o novo valor de 'key'!
console.log('Nova chave:', result.key);
console.log('Carência até:', result.gracePeriodEnds);

Response (200 OK)

{
  "data": {
    "type": "api-key",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "name": "Integração CRM",
      "prefix": "sk_e5f6g7h8",
      "status": "ACTIVE"
    }
  },
  "key": "sk_e5f6g7h8.novo_segredo_aqui",
  "gracePeriodEnds": "2024-01-17T10:30:00Z"
}

---

Revogar Chave

POST /api/v1/api-keys/:id/revoke

Revoga uma chave, impedindo qualquer nova autenticação imediatamente. O histórico de uso é mantido.

cURL

curl -X POST 'https://api-keys.stg.catalisa.app/api/v1/api-keys/550e8400-e29b-41d4-a716-446655440000/revoke' \
  -H 'Authorization: Bearer SEU_TOKEN'

JavaScript

const keyId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://api-keys.stg.catalisa.app/api/v1/api-keys/${keyId}/revoke`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

if (response.ok) {
  console.log('Chave revogada com sucesso');
}

---

Excluir Chave

DELETE /api/v1/api-keys/:id

Remove permanentemente uma chave de API.

cURL

curl -X DELETE 'https://api-keys.stg.catalisa.app/api/v1/api-keys/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer SEU_TOKEN'

JavaScript

const keyId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://api-keys.stg.catalisa.app/api/v1/api-keys/${keyId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

// Status 204 No Content = sucesso

Response (204 No Content)

Sem corpo de resposta.

---

Erros Comuns

Código	Erro	Descrição
400	VALIDATION	Campos obrigatórios ausentes ou inválidos
404	NOT_FOUND	Chave não encontrada
409	CONFLICT	Nome de chave já existe na organização
409	CONFLICT	Chave já revogada