Skip to main content

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.
Segurança: Trate suas API keys como senhas. Nunca as compartilhe publicamente, não as inclua em código versionado (Git) e rotacione-as periodicamente.

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
Ambiente:
  • Production: Para aplicações em produção
  • Sandbox: Para desenvolvimento e testes
Permissões (opcional): Por padrão, a key herda permissões do seu usuário. Você pode restringir:
  • Read: Apenas leitura de dados
  • Write: Criar e modificar entidades
  • Delete: Deletar entidades
  • Execute: Executar regras e integrações
4

Copie a API Key

IMPORTANTE: A API key completa será mostrada apenas uma vez. Copie-a imediatamente para um local seguro.
A key terá este formato:
gk_production_z1UGrahVx9NA2NG6Pj-6ZuZlFf64CEV73SpUqtt_4fflydka8MmdVAxT0cLqO3d5
Prefixos:
  • gk_production_... - Production key
  • gk_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
❌ Nunca faça:
  • 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 header Authorization:
curl https://api.gu1.ai/entities \
  -H "Authorization: Bearer gk_production_YOUR_API_KEY" \
  -H "Content-Type: application/json"

Exemplos de Código

const GUENO_API_KEY = process.env.GUENO_API_KEY;

// Usando fetch nativo
const response = await fetch('https://api.gu1.ai/entities', {
  headers: {
    'Authorization': `Bearer ${GUENO_API_KEY}`,
    'Content-Type': 'application/json'
  }
});
const data = await response.json();

// Usando SDK do gu1
import { GueoClient } from '@gueno/sdk';

const client = new GueoClient({
  apiKey: GUENO_API_KEY
});

const entities = await client.entities.list();

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

Esta ação é irreversível. Todas as integrações usando esta key pararão de funcionar imediatamente.
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:
  1. Deploy da nova key em um servidor
  2. Monitore por alguns dias
  3. Deploy no restante dos servidores
  4. 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.
Frequência de Rotação: Recomendamos rotar API keys de produção a cada 90 dias ou imediatamente se houver suspeita de comprometimento.

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

Apenas leitura✅ Permitido:
  • Listar entidades
  • Ver detalhes de alertas
  • Consultar regras
  • Ler investigações
❌ Bloqueado:
  • Criar entidades
  • Modificar dados
  • Deletar recursos
  • Executar integrações
Casos de uso:
  • 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

PlanoRequisições/minRequisições/diaBurst
Starter6010.00010
Professional300100.00050
Enterprise1.000Ilimitado200
Burst: Número máximo de requisições simultâneas.

Headers de Rate Limit

A API retorna informações de limite nos headers:
HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640995200
  • X-RateLimit-Limit: Limite total por janela
  • X-RateLimit-Remaining: Requisições restantes
  • X-RateLimit-Reset: Timestamp Unix quando o limite reseta

Tratamento de Rate Limit

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);

      // Rate limit atingido
      if (response.status === 429) {
        const resetTime = response.headers.get('X-RateLimit-Reset');
        const waitTime = resetTime
          ? (parseInt(resetTime) * 1000) - Date.now()
          : Math.pow(2, i) * 1000; // Exponential backoff

        console.log(`Rate limit atingido. Aguardando ${waitTime}ms...`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }

      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
    }
  }
}

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:
.env
.env.local
secrets.json

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
Detectando Uso Suspeito:
  • IPs inesperados
  • Horários incomuns (madrugada)
  • Endpoints não usados pela sua aplicação
  • Taxa de erros alta (401, 403)
  • Volume anormal de requisições

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

// server.js - Receber webhooks do gu1
const express = require('express');
const app = express();

app.post('/webhooks/gueno', express.json(), (req, res) => {
  const signature = req.headers['x-gueno-signature'];
  const payload = req.body;

  // Verificar assinatura (recomendado)
  if (!verifySignature(payload, signature)) {
    return res.status(401).send('Invalid signature');
  }

  // Processar evento
  switch (payload.event) {
    case 'alert.created':
      console.log('Novo alerta:', payload.data);
      // Enviar notificação, criar ticket, etc.
      break;
    case 'entity.updated':
      console.log('Entidade atualizada:', payload.data);
      break;
  }

  res.status(200).send('OK');
});

app.listen(3000);

Sincronização de Dados

# sync_entities.py - Sincronizar entidades com CRM
import os
from gueno import GueoClient
from crm import CRMClient

gueno_client = GueoClient(api_key=os.environ['GUENO_API_KEY'])
crm_client = CRMClient(api_key=os.environ['CRM_API_KEY'])

# Buscar entidades recentes do gu1
entities = gueno_client.entities.list(
    created_after='2025-01-01',
    status='approved'
)

# Sincronizar com CRM
for entity in entities:
    crm_client.contacts.create({
        'name': entity.person.name,
        'email': entity.person.email,
        'risk_score': entity.risk_score,
        'gueno_id': entity.id
    })

print(f'Sincronizadas {len(entities)} entidades')

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?


Última atualização: Janeiro 2025