Skip to main content

​
Visão geral

gu1 usa chaves API para autenticar solicitações. Todas as solicitações de API devem incluir sua chave API no cabeçalho Authorization usando o esquema Bearer. 
Authorization: Bearer YOUR_API_KEY
Mantenha suas chaves API seguras! Nunca as envie para controle de versão ou compartilhe publicamente.

​
Obtendo sua chave API

1

Fazer login no Dashboard

Navegue até app.gu1.ai e faça login em sua conta
2

Acessar seção de chaves API

Clique em Configurações → Chaves API na barra lateral
3

Criar nova chave

Clique no botão Criar chave API
4

Configurar chave

  • Dê um nome descritivo à sua chave (por exemplo, “API de produção”, “Desenvolvimento”)
  • Defina permissões (leitura, escrita, admin)
  • Opcionalmente defina uma data de expiração
5

Copiar e armazenar

Copie a chave gerada imediatamente - ela será mostrada apenas uma vez!

​
Usando sua chave API

Inclua sua chave API no cabeçalho Authorization de cada solicitação: 
curl http://api.gu1.ai/entities \
  -H "Authorization: Bearer sk_live_abc123..."

​
Exemplo com diferentes métodos

curl -X POST http://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "company", "name": "Acme Corp"}'

​
Tipos de chaves API

gu1 oferece diferentes tipos de chaves API para diferentes ambientes:

Chaves de produção

Começam com sk_live_Usadas para ambientes de produção. Todas as operações são reais e afetam seus dados ao vivo.

Chaves de teste

Começam com sk_test_Usadas para desenvolvimento e testes. As operações não afetam seus dados de produção.

​
Permissões

As chaves API podem ter diferentes níveis de permissão:
PermissãoDescriçãoCaso de uso
ReadVisualizar entidades, regras e dadosDashboards de análise, relatórios
WriteCriar e atualizar entidadesIngestão de dados, integrações API
AdminAcesso completo incluindo gerenciamento de chavesAutomação de infraestrutura
Siga o princípio do menor privilégio - conceda apenas as permissões mínimas necessárias para cada integração.

​
Melhores práticas

  • Armazene chaves API em variáveis de ambiente ou sistemas de gerenciamento de segredos
  • Nunca codifique chaves em seu código-fonte
  • Nunca envie chaves para controle de versão (use arquivos .env e .gitignore)
  • Rotacione chaves API regularmente (recomendado a cada 90 dias)
  • Crie novas chaves antes de revogar as antigas para evitar tempo de inatividade
  • Atualize todos os sistemas que usam a chave antiga
  • Revise regularmente a atividade das chaves API no dashboard
  • Configure alertas para padrões de uso incomuns
  • Revogue imediatamente chaves comprometidas
  • Use chaves de teste para desenvolvimento e staging
  • Use chaves de produção apenas em produção
  • Nunca use chaves de produção em máquinas de desenvolvedores

​
Respostas de erro

Se a autenticação falhar, você receberá uma destas respostas de erro:

​
Chave API ausente

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "No API key provided"
  }
}
Status HTTP: 401 Unauthorized

​
Chave API inválida

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key provided"
  }
}
Status HTTP: 401 Unauthorized

​
Chave API expirada

{
  "error": {
    "code": "EXPIRED_API_KEY",
    "message": "API key has expired"
  }
}
Status HTTP: 401 Unauthorized

​
Permissões insuficientes

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have permission to perform this action"
  }
}
Status HTTP: 403 Forbidden

​
Limite de Taxa

As chaves API estão sujeitas a limites de taxa com base no seu plano:
PlanoSolicitações por horaSolicitações por dia
Free10010,000
Starter300100,000
Professional1,200500,000
EnterprisePersonalizadoPersonalizado

​
Cabeçalhos de Limite de Taxa

Todas as respostas da API incluem informações de limite de taxa nos cabeçalhos: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 85
X-RateLimit-Reset: 2025-01-15T10:00:00Z
CabeçalhoDescrição
X-RateLimit-LimitMáximo de solicitações permitidas na janela atual
X-RateLimit-RemainingNúmero de solicitações restantes na janela atual
X-RateLimit-ResetTimestamp ISO 8601 quando o limite de taxa é reiniciado

​
Resposta de Limite de Taxa Excedido

Quando você exceder os limites de taxa, receberá: 
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Você excedeu o limite de taxa da API. Por favor aguarde antes de fazer mais solicitações.",
  "retryAfter": 3600,
  "limit": 100,
  "remaining": 0,
  "resetAt": "2025-01-15T10:00:00Z"
}
Status HTTP: 429 Too Many Requests Cabeçalhos de Resposta: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2025-01-15T10:00:00Z
Retry-After: 3600
Monitore os cabeçalhos de limite de taxa em suas respostas para implementar limitação de taxa proativa em sua aplicação. O cabeçalho Retry-After indica quantos segundos você deve aguardar antes de tentar novamente.

​
Testando sua chave API

Use este teste simples para verificar se sua chave API está funcionando: 
curl http://api.gu1.ai/auth/test \
  -H "Authorization: Bearer YOUR_API_KEY"
Resposta de sucesso: 
{
  "authenticated": true,
  "organization_id": "org_abc123",
  "permissions": ["read", "write"],
  "key_type": "live"
}

​
Próximos passos

Criar sua primeira entidade

Comece a usar a API para criar entidades

Definir esquemas personalizados

Configure o mapeamento de dados para seu caso de uso

Configurar webhooks

Receba notificações em tempo real

Guia de integração

Siga nosso guia completo de integração