API para desenvolvedores

A aba Developers é onde você emite chaves de API para acesso programático ao Entergram. Disponível no plano Pro (e em seats Pro do espaço de trabalho). Apenas proprietários e admins.

Criando uma chave

1. “Create API key”
2. Dê um nome a ela (algo que você reconheça em uma lista de revogação mais tarde)
3. Escolha os escopos — permissões granulares como:
   • workspace.read
   • members.read
   • accounts.read
   • contacts.read
   • chats.read / chats.write
   • custom_fields.read / custom_fields.write
4. O TTL padrão é de 90 dias; você pode escolher uma duração menor
5. Opcional: restringir a uma lista de faixas de IP CIDR
6. Clique em Create — a chave completa é exibida uma única vez. Copie-a imediatamente; o Entergram nunca a exibe novamente.

Por baixo dos panos

• As chaves são armazenadas como hashes unidirecionais — a chave bruta nunca fica em disco
• Cada requisição registra prefixo, IP e user agent para auditoria
• A revogação é imediata
• Chaves expiradas retornam 403 automaticamente
• Cada chamada de API tem escopo de espaço de trabalho — uma chave só pode operar no espaço de trabalho que a emitiu

Gerenciando chaves

Pela aba Developers:

• Veja o prefixo, a data de criação, os escopos, o TTL e as informações de último uso de cada chave
• Copie o prefixo (não o segredo)
• Revogue ou rotacione uma chave
• Rotacionar = criar uma nova chave com os mesmos escopos e depois revogar a antiga assim que sua integração estiver migrada

Exemplo: rotacionar uma chave vazada

1. Você percebe que um engenheiro colou uma chave em um rastreador de issues público
2. Aba Developers → encontre a chave → Revoke (tem efeito imediato)
3. Crie uma nova chave com os mesmos escopos e allowlist de IP
4. Implante a nova chave na sua integração
5. Verifique as informações de último uso da chave antiga para confirmar que não há mais tráfego

Exemplo: gerar uma chave para um job de CI

1. Aba Developers → Create API key
2. Dê o nome ci-deploy-bot
3. Escopos: apenas workspace.read e chats.read (menor privilégio)
4. TTL: 30 dias
5. Allowlist de IP: os IPs de saída do provedor de CI
6. Copie a chave e defina-a como um segredo no CI
7. Rotacione antes de o TTL expirar

Integração com o Make.com

Os planos Pro incluem uma integração com o Make.com para que você possa conectar o Entergram a automações low-code sem escrever código de API você mesmo. Disponível na área de integrações do espaço de trabalho.

Respostas da API

Erros HTTP comuns que você verá:

• 401 — a chave está expirada, revogada ou errada para o espaço de trabalho
• 403 — a chave não tem o escopo necessário, ou a requisição vem de um IP fora da allowlist
• 429 — você atingiu um limite de taxa; recue e tente novamente