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. As chaves seguem o formato gk_<ambiente>_... (veja Formato da chave API). 
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”)
  • Abra Gerenciar permissões e selecione permissões granulares (pares recurso:ação) alinhados ao RBAC do workspace. Conceda apenas o necessário para a integração.
  • 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 gk_prod_SUA_CHAVE_AQUI"

​
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"}'

​
Formato da chave API

As chaves são strings opacas com o prefixo gk_, um segmento de ambiente e um sufixo aleatório (por exemplo gk_prod_...). O segmento reflete o ambiente escolhido ao criar a chave (produção vs sandbox). Use chaves de produção apenas com organizações e dados de produção.

​
Permissões

As permissões são granulares: no dashboard você define recursos e ações permitidos (o mesmo modelo recurso:ação do RBAC do workspace). Cada integração deve receber o conjunto mínimo necessário para os endpoints que usa.
Aplique o menor privilégio: preferência por concessões explícitas recurso:ação em vez de acesso amplo.

​
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: 
{
  "valid": true,
  "apiKey": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "API de produção",
    "environment": "prod",
    "organizationId": "550e8400-e29b-41d4-a716-446655440001",
    "scopes": [],
    "rateLimit": 1000,
    "rateLimitRemaining": 999,
    "expiresAt": null,
    "lastUsedAt": "2026-01-10T12:00:00.000Z"
  }
}

​
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

Webhooks

Receba notificações em tempo real

Fluxo KYC completo

Guia de integração KYC ponta a ponta