Tutorial Interativo
Este vídeo é interativo. Você pode clicar nos elementos para navegar entre diferentes seções e aprender no seu próprio ritmo.
Visão Geral
As API Keys do gu1 permitem que você integre a plataforma com seus próprios sistemas, automatize workflows e acesse dados programaticamente.O que são API Keys?
Uma API Key é uma credencial de autenticação que identifica sua aplicação ao fazer requisições à API do gu1. É como uma senha, mas projetada para ser usada por aplicações em vez de usuários humanos.Tipos de API Keys
Production Key
Para dados reais
- Acessa dados de produção
- Modifica entidades reais
- Cobra por uso de integrações
- Envia webhooks para endpoints reais
- Requer máxima segurança
Sandbox Key
Para desenvolvimento e testes
- Acessa dados de sandbox
- Ambiente isolado
- Sem custo adicional
- Ideal para desenvolvimento
- Pode ser compartilhada em equipes de dev
Criar uma Nova API Key
1
Acesse Configurações
Navegue até Settings > API Keys no menu lateral esquerdo.
2
Clique em 'Create API Key'
No canto superior direito, clique no botão + Create API Key (azul).
3
Configure a API Key
Preencha as informações:Nome da Key:
- Use um nome descritivo (ex: “Integration Zapier”, “Mobile App”, “Data Pipeline”)
- Isso ajuda a identificar o uso mais tarde
- Production: Para aplicações em produção
- Sandbox: Para desenvolvimento e testes
- Read: Apenas leitura de dados
- Write: Criar e modificar entidades
- Delete: Deletar entidades
- Execute: Executar regras e integrações
4
Copie a API Key
A key terá este formato:Prefixos:
gk_production_...- Production keygk_sandbox_...- Sandbox key
5
Armazene de Forma Segura
Opções recomendadas:
- Gerenciador de senhas: 1Password, LastPass, Bitwarden
- Variáveis de ambiente:
.env(não commitar no Git!) - Secret managers: AWS Secrets Manager, Google Secret Manager, HashiCorp Vault
- CI/CD secrets: GitHub Secrets, GitLab CI Variables
- Commitar no código
- Compartilhar por email/Slack
- Incluir em screenshots
- Deixar em arquivos de log
Usar sua API Key
Autenticação HTTP
Todas as requisições devem incluir a API key no headerAuthorization:
Exemplos de Código
- JavaScript/Node.js
- Python
- PHP
- Ruby
Gerenciar API Keys Existentes
Ver Todas as Keys
Na página Settings > API Keys, você verá uma lista de todas as keys ativas:Nome
Nome descritivo que você definiu
Ambiente
Production ou Sandbox
Último Uso
Quando foi usada pela última vez
Criada Por
Quem criou a key
Criada Em
Data de criação
Permissões
Nível de acesso (Read, Write, etc.)
Nota de Segurança: Apenas os primeiros e últimos 4 caracteres da key são mostrados (ex:
gk_p...3d5). A key completa não pode ser recuperada.Revogar uma API Key
Se uma key foi comprometida ou não é mais necessária:1
Identifique a Key
Na lista de API keys, localize a key que deseja revogar.
2
Clique em 'Revoke'
Clique nos três pontos ao lado da key e selecione Revoke.
3
Confirme
Digite o nome da key para confirmar e clique em Revoke API Key.
4
Atualize suas Integrações
Se necessário, crie uma nova key e atualize seus sistemas.
Rotar uma API Key
Rotação é a prática de substituir uma key periodicamente por segurança:1
Crie uma Nova Key
Siga os passos de criação e dê um nome como “Integration Zapier (v2)”.
2
Atualize suas Integrações
Substitua a key antiga pela nova em todos os seus sistemas.Recomendação: Faça isso gradualmente em produção:
- Deploy da nova key em um servidor
- Monitore por alguns dias
- Deploy no restante dos servidores
- Revogue a key antiga
3
Verifique Funcionamento
Monitore logs e webhooks para garantir que tudo está funcionando.
4
Revogue a Key Antiga
Após confirmar que a nova key funciona, revogue a antiga.
Permissões de API Keys
Você pode criar keys com permissões específicas para princípio do menor privilégio:Níveis de Permissão
- Read-Only
- Write
- Full Access
- Custom
Apenas leitura✅ Permitido:
- Listar entidades
- Ver detalhes de alertas
- Consultar regras
- Ler investigações
- Criar entidades
- Modificar dados
- Deletar recursos
- Executar integrações
- Dashboards externos
- Relatórios e analytics
- Auditoria de dados
Rate Limits e Quotas
Para proteger a infraestrutura, todas as API keys têm limites de uso:Limites Padrão
| Plano | Requisições/min | Requisições/dia | Burst |
|---|---|---|---|
| Starter | 60 | 10.000 | 10 |
| Professional | 300 | 100.000 | 50 |
| Enterprise | 1.000 | Ilimitado | 200 |
Headers de Rate Limit
A API retorna informações de limite nos headers:X-RateLimit-Limit: Limite total por janelaX-RateLimit-Remaining: Requisições restantesX-RateLimit-Reset: Timestamp Unix quando o limite reseta
Tratamento de Rate Limit
Exemplo: Retry com Exponential Backoff
Exemplo: Retry com Exponential Backoff
Segurança e Boas Práticas
Armazenamento Seguro
Nunca exponha keys
- Use variáveis de ambiente
- Secret managers (AWS, GCP, Azure)
- Nunca commite no Git
- Adicione ao
.gitignore:
Rotação Regular
Substitua periodicamente
- Production: a cada 90 dias
- Sandbox: a cada 180 dias
- Imediatamente se comprometida
- Use automação se possível
Princípio do Menor Privilégio
Permissões mínimas necessárias
- Read-only para dashboards
- Write para integrações específicas
- Full access apenas para admins
- Custom para terceiros
Monitoramento
Acompanhe uso e anomalias
- Verifique “Último Uso” regularmente
- Configure alertas de uso anormal
- Revise keys inativas mensalmente
- Audite acessos periodicamente
Separação de Ambientes
Keys diferentes para cada ambiente
- Production key ≠ Sandbox key
- Development ≠ Staging ≠ Production
- Nunca use production key em testes
Revogação Imediata
Aja rápido em incidentes
- Key exposta no Git? Revogue agora
- Funcionário saiu? Revogue suas keys
- Integração desativada? Revogue a key
- Dúvida? Melhor revogar e recriar
Auditoria e Logs
Ver Uso de API Keys
Acesse Settings > API Keys > [Selecione uma key] > Usage Logs Você verá:- Timestamp: Quando a requisição foi feita
- Endpoint: Qual API foi chamada
- Método: GET, POST, PUT, DELETE
- Status: 200, 401, 429, etc.
- IP Address: De onde veio a requisição
- User Agent: Aplicação que fez a requisição
Alertas de Segurança
Configure notificações automáticas em Settings > Notifications > API Security:- ✅ Key usada de novo IP
- ✅ Key com muitos erros 401/403
- ✅ Key próxima ao rate limit
- ✅ Key não usada por 30 dias
- ✅ Tentativas de usar key revogada
Migração e Recuperação
Key Comprometida - Checklist
1
Revogue Imediatamente
Não espere! Vá em Settings > API Keys e revogue a key comprometida.
2
Crie Nova Key
Gere uma nova key com o mesmo nome + ” (v2)” para identificação.
3
Atualize Sistemas
Substitua a key em todos os locais:
- Variáveis de ambiente
- Secret managers
- Configurações de CI/CD
- Documentação interna
4
Verifique Logs
Revise logs de uso da key comprometida:
- Houve acesso não autorizado?
- Quais dados foram acessados?
- Precisa notificar clientes?
5
Investigue a Origem
Como a key foi exposta?
- Commit no Git público?
- Compartilhada por acidente?
- Phishing?
- Dispositivo roubado?
6
Previna Recorrência
Implemente medidas preventivas:
- Git secrets scanning
- Treinamento de segurança
- Rotação automática
- Secret managers obrigatórios
Exemplos de Integração
Webhook Receiver
Sincronização de Dados
Próximos Passos
API Reference
Documentação completa da API REST
SDK do gu1
Bibliotecas JavaScript, Python, Ruby, PHP
Webhooks
Configure notificações em tempo real
Exemplos de Código
Integrações prontas (Zapier, n8n, Make)
Precisa de Ajuda?
- Documentação: Navegue por nossas guias completas
- Email: [email protected]
- Dashboard: Acesse sua conta em app.gu1.ai
- Status da API: status.gu1.ai
Última atualização: Janeiro 2025