Chaves de API
Toda integração programática com o GCM se autentica com uma chave de API. O Zapier usa uma. Seu backend personalizado usa uma. Seu pipeline de data warehouse usa uma. Esta página explica como criá-las, definir o escopo e aposentá-las com segurança.
Gerencie as chaves em Integrations → Zapier → API Keys. (Apesar da URL, isso não é só para o Zapier — qualquer chamador externo da API do GCM usa chaves daqui.)
Criar uma chave
Clique em New key. Dê a ela um rótulo que nomeie o que vai usar a chave, não quem a criou:
- Zapier — Production — para os Zaps.
- ETL data warehouse — para sua exportação noturna.
- Site interno de diretório — para uma intranet só para funcionários que lista membros.
Quando você clica em criar, o GCM exibe a chave bruta uma única vez.
Copie-a imediatamente e guarde-a em um gerenciador de segredos de verdade — 1Password, AWS Secrets Manager, Doppler, Vault, a plataforma de sua escolha. Não a cole no Slack, em e-mail ou em uma página de wiki.
WARNING
Não armazenamos a chave bruta. O banco de dados guarda apenas um hash, mais um prefixo de 6 caracteres que você pode usar para identificar qual chave é qual sem revelar o segredo. Se você perder a chave bruta, sua única opção é revogar e emitir uma nova.
Formato da chave
As chaves se parecem com gcm_live_<32 caracteres aleatórios> ou gcm_test_<32 caracteres aleatórios> dependendo do ambiente em que foram emitidas. O prefixo é visível na lista de chaves para que você possa dizer rapidamente qual é de produção e qual é de staging sem nunca ver o segredo.
gcm_live_a1b2c3d4e5f6...
└─┬─┘└─┬─┘└──────┬──────┘
│ │ └── 32 caracteres de entropia CSPRNG
│ └── ambiente
└── produto (sempre `gcm`)Escopos
Cada chave carrega uma lista de escopos que restringem o que ela pode fazer. O padrão para chaves criadas pela interface do Zapier é read:* — acesso somente leitura a todos os recursos.
| Escopo | Concede |
|---|---|
read:* | Listar e ler todos os recursos públicos |
read:members | Apenas membros |
read:donations | Apenas doações |
write:members | Criar / atualizar membros |
write:donations | Registrar doações (para integrações contábeis) |
subscriptions:manage | Criar / excluir assinaturas de webhook |
* | Acesso completo — equivalente a admin. Use com parcimônia. |
Os escopos são aplicados pelo gateway da API, não pela lógica da aplicação — uma chave read:* chamando um endpoint de escrita recebe um 403 imediatamente, nunca chega ao RPC subjacente.
TIP
Comece toda nova integração com read:*. Só amplie o escopo quando tiver provado que o caminho de leitura funciona e tiver um requisito real de escrita. Chaves com escopo excessivo são como exploits viram catástrofes.
Usando uma chave
Envie a chave como token Bearer em toda requisição:
curl https://api.geniuschurchmanager.com/v1/members \
-H "Authorization: Bearer gcm_live_..."É isso. Sem dança de OAuth, sem assinatura por requisição — apenas o bearer. Combinado com HTTPS, isso é suficiente para as integrações para as quais a API foi projetada.
Cada requisição é registrada com o prefixo da chave, o endpoint chamado e o status da resposta. Você pode ver o timestamp do último uso na chave na interface do GCM — útil para identificar chaves que não foram usadas há meses (boas candidatas para rotação ou revogação).
Rotação
Você deve fazer rotação das chaves de API:
- Por cronograma — a cada 12 meses no mínimo.
- Na saída de funcionários — qualquer pessoa que teve acesso à chave bruta não deve poder usá-la depois de sair.
- Em suspeita de comprometimento — se uma chave aparecer em um commit Git, em uma mensagem do Slack ou em uma captura de tela, trate-a como comprometida.
Procedimento de rotação:
- Emita uma nova chave com os mesmos escopos.
- Implante a nova chave no consumidor (conexão do Zapier, variável de ambiente, gerenciador de segredos).
- Verifique se o consumidor está usando a nova chave observando o timestamp last_used se mover.
- Revogue a chave antiga.
O GCM não suporta atualmente janelas de rotação sobrepostas — a chave antiga funciona até você revogá-la, e a nova chave funciona a partir do momento da criação. Planeje sua transição.
Revogação
Clique no ícone de lixeira ao lado de qualquer chave. A chave é marcada com revoked_at imediatamente; a próxima requisição com ela recebe um 401.
WARNING
Revogar uma chave em produção quebra instantaneamente qualquer consumidor que a esteja usando. Os Zaps param, sua tarefa de ETL lança erro, o site interno de diretório fica em branco. Coordene a rotação, depois revogue.
Chaves revogadas permanecem na lista (acinzentadas) para que você possa auditar quando foram emitidas, quando foram usadas pela última vez e quando foram aposentadas. Para apagar permanentemente uma chave revogada antiga, contate o suporte da plataforma — auditores geralmente preferem revogações a exclusões.
Auditando o uso
A lista de chaves mostra para cada chave:
- Timestamp de criação.
- Timestamp do último uso (rolante — atualiza em segundos após uma requisição).
- Escopos.
- Timestamp de revogação, se revogada.
Para auditoria mais profunda — contagens por endpoint, distribuição de códigos de resposta, detecção de abuso — admins da plataforma têm acesso à tabela api_request_log nas exportações do BigQuery. Entre em contato se precisar de um recorte específico.
Limites
| Limite | Padrão |
|---|---|
| Chaves por organização | 20 |
| Requisições por segundo por chave | 60 |
| Requisições por hora por chave | 10.000 |
| Requisições simultâneas por chave | 20 |
Esses limites são deliberadamente generosos para integrações legítimas e apertados o suficiente para tornar a enumeração por força bruta impraticável. Se você atingir um limite, provavelmente tem um loop descontrolado em algum lugar.
O que uma chave de API não pode fazer
Por segurança, as chaves de API deliberadamente não podem:
- Fazer login interativamente (sem sessão, sem acesso à interface).
- Gerenciar outras chaves de API (apenas a interface do Zapier pode, e apenas admins chegam lá).
- Personificar usuários (o sistema JWT que controla a personificação de admin da plataforma é separado).
- Burlar a segurança em nível de linha — toda consulta ainda fica restrita a
current_org_id()derivada da organização da chave.
Esses são guarda-corpos, não recursos: mesmo uma chave comprometida não pode escalar além da organização que a possui.
Referências cruzadas
- Integração com Zapier — o consumidor mais comum dessas chaves.
- Webhooks de saída — usa as mesmas chaves para criar assinaturas.
- Autenticação da API — referência completa da API para usar uma chave.