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

Precisa de Ajuda?


Última atualização: Janeiro 2025