Autenticação

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

Fazer login no Dashboard

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

Acessar seção de chaves API

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

Criar nova chave

Clique no botão Criar chave API

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

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

const response = await fetch('http://api.gu1.ai/entities', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'company',
    name: 'Acme Corp'
  })
});

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
}

data = {
    'type': 'company',
    'name': 'Acme Corp'
}

response = requests.post(
    'http://api.gu1.ai/entities',
    headers=headers,
    json=data
)

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

Armazenamento seguro

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)

Rotação de chaves

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

Monitorar uso

Revise regularmente a atividade das chaves API no dashboard
Configure alertas para padrões de uso incomuns
Revogue imediatamente chaves comprometidas

Separação de ambientes

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:

Plano	Solicitações por hora	Solicitações por dia
Free	100	10,000
Starter	300	100,000
Professional	1,200	500,000
Enterprise	Personalizado	Personalizado

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çalho	Descrição
`X-RateLimit-Limit`	Máximo de solicitações permitidas na janela atual
`X-RateLimit-Remaining`	Número de solicitações restantes na janela atual
`X-RateLimit-Reset`	Timestamp 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

​Visão geral

​Obtendo sua chave API

​Usando sua chave API

​Exemplo com diferentes métodos

​Formato da chave API

​Permissões

​Melhores práticas

​Respostas de erro

​Chave API ausente

​Chave API inválida

​Chave API expirada

​Permissões insuficientes

​Limite de Taxa

​Cabeçalhos de Limite de Taxa

​Resposta de Limite de Taxa Excedido

​Testando sua chave API

​Próximos passos

Criar sua primeira entidade

Definir esquemas personalizados

Webhooks

Fluxo KYC completo

Visão geral

Obtendo sua chave API

Usando sua chave API

Exemplo com diferentes métodos

Formato da chave API

Permissões

Melhores práticas

Respostas de erro

Chave API ausente

Chave API inválida

Chave API expirada

Permissões insuficientes

Limite de Taxa

Cabeçalhos de Limite de Taxa

Resposta de Limite de Taxa Excedido

Testando sua chave API

Próximos passos