Como funcionam as chaves de API?

As chaves de API são suas credenciais de autenticação para acessar a API da Cathopic. Entender como elas funcionam é essencial para uma integração de API segura e eficaz.

O que é uma chave de API?

Uma chave de API é um token secreto exclusivo que identifica seu aplicativo e autoriza o acesso à API da Cathopic:

• Uma longa sequência alfanumérica (por exemplo, sk_live_abc123xyz789...)

• Atua como autenticação e autorização

• Vinculada à sua conta e ao faturamento da Cathopic

• Pode estar ativa ou inativa

Ciclo de vida da chave

Criação:

1. Gere chaves em Configurações → API

2. Dê a cada chave um nome descritivo ("Website de Produção", "Staging", "Aplicativo Mobile")

3. Copie a chave completa imediatamente — ela é exibida apenas uma vez

4. Armazene com segurança (variáveis de ambiente, gerenciador de segredos, gerenciador de senhas)

Uso:

• Inclua no cabeçalho HTTP x-api-key em cada solicitação

• As chaves são validadas no servidor em cada solicitação

• Todo o uso da API é rastreado e faturado para sua conta

Desativação:

• As chaves podem ser desativadas temporariamente sem exclusão

• Útil para solucionar problemas ou pausar uma integração específica

• Pode ser reativada a qualquer momento

Exclusão:

• Remove a chave permanentemente

• Não pode ser desfeita nem recuperada

• Todas as solicitações com essa chave falharão imediatamente

Diretrizes para gerenciamento de chaves

Segurança:

• Nunca envie chaves para controle de versão: Use arquivos .env e adicione-os ao .gitignore

• Nunca exponha em código do lado do cliente: As chaves de API devem ser usadas apenas no servidor

• Use variáveis de ambiente: Armazene as chaves em process.env.CATHOPIC_API_KEY ou equivalente

• Gire regularmente: Troque as chaves periodicamente (trimestralmente ou após mudanças na equipe)

• Use chaves separadas por ambiente: Chaves diferentes para desenvolvimento, staging e produção

Organização:

• Nomes descritivos: Nomeie as chaves por finalidade: "Website de Produção", "App iOS", "Sistema de E-mail"

• Documente a propriedade: Registre qual membro da equipe criou cada chave

• Auditorias regulares: Revise as chaves ativas mensalmente e remova as que não são usadas

Múltiplas chaves de API

Você pode criar várias chaves de API para finalidades diferentes:

• Por ambiente: Chaves separadas para desenvolvimento, staging e produção

• Por aplicativo: Chaves diferentes para website, aplicativo mobile, ferramentas internas

• Por membro da equipe: Chaves individuais para desenvolvedores (mais fácil de rastrear e revogar)

Todas as chaves sob sua conta compartilham o mesmo faturamento. O uso de todas as chaves é combinado na sua fatura mensal.

Monitorar o uso da chave

Rastreie a atividade de cada chave:

1. Vá para Configurações → API

2. Veja a lista de todas as chaves com as datas da última utilização

3. Clique em uma chave para ver estatísticas detalhadas de uso

4. Monitore por atividades inesperadas

O que fazer se uma chave for comprometida

Se você acredita que uma chave de API foi exposta:

1. Exclua ou desative imediatamente a chave em Configurações → API

2. Gere uma nova chave de substituição

3. Atualize seu aplicativo com a nova chave

4. Revise os logs de uso para qualquer atividade suspeita

5. Entre em contato com o suporte se você vir uso não autorizado

Exemplo: armazenar chaves com segurança

Node.js com variáveis de ambiente:

// arquivo .env (adicione ao .gitignore!)
CATHOPIC_API_KEY=sk_live_abc123xyz789...
// Seu código
require('dotenv').config();
const apiKey = process.env.CATHOPIC_API_KEY;
fetch('https://api.cathopic.com/resources', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ query: 'Jesus' })
});

Python com variáveis de ambiente:

import os
import requests
api_key = os.environ.get('CATHOPIC_API_KEY')
response = requests.post(
    'https://api.cathopic.com/resources',
    headers={'x-api-key': api_key},
    json={'query': 'Jesus'}
)