> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Como Criar e Gerenciar API Keys

> Guia completo para gerar, configurar e gerenciar API keys de forma segura no gu1 — no painel gu1 com orientação passo a passo, com exemplos para gerenciar api.

## Tutorial Interativo

<iframe src="https://clueso.site/embed/uz09raz7wlj1varr" frameBorder="0" webkitallowfullscreen mozallowfullscreen allowFullScreen className="w-full aspect-video rounded-xl mb-6" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" />

<Info>
  Este vídeo é interativo. Você pode clicar nos elementos para navegar entre diferentes seções e aprender no seu próprio ritmo.
</Info>

## 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.

<Tip>
  **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.
</Tip>

## Tipos de API Keys

<CardGroup cols={2}>
  <Card title="Production Key" icon="building" color="#10b981">
    **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
  </Card>

  <Card title="Sandbox Key" icon="flask" color="#f59e0b">
    **Para desenvolvimento e testes**

    * Acessa dados de sandbox
    * Ambiente isolado
    * Sem custo adicional
    * Ideal para desenvolvimento
    * Pode ser compartilhada em equipes de dev
  </Card>
</CardGroup>

## Criar uma Nova API Key

<Steps>
  <Step title="Abra API Keys">
    Vá para **API Keys** em [https://app.gu1.ai/org-api-keys](https://app.gu1.ai/org-api-keys) (`/org-api-keys`).
  </Step>

  <Step title="Clique em 'Create API Key'">
    No canto superior direito, clique no botão **+ Create API Key** (azul).
  </Step>

  <Step title="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
  </Step>

  <Step title="Copie a API Key">
    <Warning>
      **IMPORTANTE**: A API key completa será mostrada **apenas uma vez**. Copie-a imediatamente para um local seguro.
    </Warning>

    A key terá este formato:

    ```
    gk_production_z1UGrahVx9NA2NG6Pj-6ZuZlFf64CEV73SpUqtt_4fflydka8MmdVAxT0cLqO3d5
    ```

    **Prefixos**:

    * `gk_production_...` - Production key
    * `gk_sandbox_...` - Sandbox key
  </Step>

  <Step title="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
  </Step>
</Steps>

## Usar sua API Key

### Autenticação HTTP

Todas as requisições devem incluir a API key no header `Authorization`:

```bash theme={null}
curl https://api.gu1.ai/entities \
  -H "Authorization: Bearer gk_production_YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### Exemplos de Código

<Tabs>
  <Tab title="JavaScript/Node.js">
    ```javascript theme={null}
    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();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    import requests

    GUENO_API_KEY = os.environ['GUENO_API_KEY']

    # Usando requests
    response = requests.get(
        'https://api.gu1.ai/entities',
        headers={
            'Authorization': f'Bearer {GUENO_API_KEY}',
            'Content-Type': 'application/json'
        }
    )
    data = response.json()

    # Usando SDK do gu1
    from gueno import GueoClient

    client = GueoClient(api_key=GUENO_API_KEY)
    entities = client.entities.list()
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    <?php
    $apiKey = getenv('GUENO_API_KEY');

    $ch = curl_init('https://api.gu1.ai/entities');
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    $data = json_decode($response, true);
    curl_close($ch);
    ?>
    ```
  </Tab>

  <Tab title="Ruby">
    ```ruby theme={null}
    require 'net/http'
    require 'json'

    api_key = ENV['GUENO_API_KEY']

    uri = URI('https://api.gu1.ai/entities')
    request = Net::HTTP::Get.new(uri)
    request['Authorization'] = "Bearer #{api_key}"
    request['Content-Type'] = 'application/json'

    response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
      http.request(request)
    end

    data = JSON.parse(response.body)
    ```
  </Tab>
</Tabs>

## Gerenciar API Keys Existentes

### Ver Todas as Keys

Na página **API Keys** ([/org-api-keys](https://app.gu1.ai/org-api-keys)), você verá uma lista de todas as keys ativas:

<CardGroup cols={3}>
  <Card title="Nome" icon="tag">
    Nome descritivo que você definiu
  </Card>

  <Card title="Ambiente" icon="toggle-on">
    Production ou Sandbox
  </Card>

  <Card title="Último Uso" icon="clock">
    Quando foi usada pela última vez
  </Card>

  <Card title="Criada Por" icon="user">
    Quem criou a key
  </Card>

  <Card title="Criada Em" icon="calendar">
    Data de criação
  </Card>

  <Card title="Permissões" icon="shield">
    Nível de acesso (Read, Write, etc.)
  </Card>
</CardGroup>

<Info>
  **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.
</Info>

### Revogar uma API Key

Se uma key foi comprometida ou não é mais necessária:

<Steps>
  <Step title="Identifique a Key">
    Na lista de API keys, localize a key que deseja revogar.
  </Step>

  <Step title="Clique em 'Revoke'">
    Clique nos três pontos ao lado da key e selecione **Revoke**.
  </Step>

  <Step title="Confirme">
    <Warning>
      Esta ação é **irreversível**. Todas as integrações usando esta key pararão de funcionar imediatamente.
    </Warning>

    Digite o nome da key para confirmar e clique em **Revoke API Key**.
  </Step>

  <Step title="Atualize suas Integrações">
    Se necessário, crie uma nova key e atualize seus sistemas.
  </Step>
</Steps>

### Rotar uma API Key

**Rotação** é a prática de substituir uma key periodicamente por segurança:

<Steps>
  <Step title="Crie uma Nova Key">
    Siga os passos de criação e dê um nome como "Integration Zapier (v2)".
  </Step>

  <Step title="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
  </Step>

  <Step title="Verifique Funcionamento">
    Monitore logs e webhooks para garantir que tudo está funcionando.
  </Step>

  <Step title="Revogue a Key Antiga">
    Após confirmar que a nova key funciona, revogue a antiga.
  </Step>
</Steps>

<Tip>
  **Frequência de Rotação**: Recomendamos rotar API keys de produção a cada **90 dias** ou imediatamente se houver suspeita de comprometimento.
</Tip>

## 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

<Tabs>
  <Tab title="Read-Only">
    **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
  </Tab>

  <Tab title="Write">
    **Leitura e escrita**

    ✅ Permitido:

    * Tudo do Read-Only +
    * Criar entidades
    * Atualizar dados
    * Criar alertas
    * Modificar investigações

    ❌ Bloqueado:

    * Deletar entidades
    * Executar regras manualmente
    * Modificar configurações

    **Casos de uso**:

    * Integrações de onboarding
    * Automação de workflows
    * Sincronização bidirecional
  </Tab>

  <Tab title="Full Access">
    **Acesso completo**

    ✅ Permitido:

    * Tudo do Write +
    * Deletar recursos
    * Executar integrações
    * Modificar regras
    * Configurar webhooks

    ⚠️ **Cuidado**: Requer máxima segurança

    **Casos de uso**:

    * Ferramentas de administração
    * Scripts de manutenção
    * Integrações complexas
  </Tab>

  <Tab title="Custom">
    **Permissões granulares**

    Selecione exatamente o que a key pode fazer:

    ```json theme={null}
    {
      "entities": {
        "create": true,
        "read": true,
        "update": false,
        "delete": false
      },
      "alerts": {
        "create": true,
        "read": true,
        "resolve": false
      },
      "rules": {
        "read": true,
        "execute": false
      }
    }
    ```

    **Casos de uso**:

    * Integrações de terceiros
    * Ferramentas de clientes
    * APIs públicas
  </Tab>
</Tabs>

## Rate Limits e Quotas

Para proteger a infraestrutura, todas as API keys têm limites de uso:

### Limites Padrão

| Plano            | Requisições/min | Requisições/dia | Burst |
| ---------------- | --------------- | --------------- | ----- |
| **Starter**      | 60              | 10.000          | 10    |
| **Professional** | 300             | 100.000         | 50    |
| **Enterprise**   | 1.000           | Ilimitado       | 200   |

**Burst**: Número máximo de requisições simultâneas.

### Headers de Rate Limit

A API retorna informações de limite nos headers:

```http theme={null}
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

<Accordion title="Exemplo: Retry com Exponential Backoff">
  ```javascript theme={null}
  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));
      }
    }
  }
  ```
</Accordion>

## Segurança e Boas Práticas

<CardGroup cols={2}>
  <Card title="Armazenamento Seguro" icon="lock">
    **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
    ```
  </Card>

  <Card title="Rotação Regular" icon="rotate">
    **Substitua periodicamente**

    * Production: a cada 90 dias
    * Sandbox: a cada 180 dias
    * Imediatamente se comprometida
    * Use automação se possível
  </Card>

  <Card title="Princípio do Menor Privilégio" icon="shield-halved">
    **Permissões mínimas necessárias**

    * Read-only para dashboards
    * Write para integrações específicas
    * Full access apenas para admins
    * Custom para terceiros
  </Card>

  <Card title="Monitoramento" icon="chart-line">
    **Acompanhe uso e anomalias**

    * Verifique "Último Uso" regularmente
    * Configure alertas de uso anormal
    * Revise keys inativas mensalmente
    * Audite acessos periodicamente
  </Card>

  <Card title="Separação de Ambientes" icon="layer-group">
    **Keys diferentes para cada ambiente**

    * Production key ≠ Sandbox key
    * Development ≠ Staging ≠ Production
    * Nunca use production key em testes
  </Card>

  <Card title="Revogação Imediata" icon="ban">
    **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
  </Card>
</CardGroup>

## Auditoria e Logs

### Ver Uso de API Keys

Acesse **API Keys** ([/org-api-keys](https://app.gu1.ai/org-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

<Tip>
  **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
</Tip>

### 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

<Steps>
  <Step title="Revogue Imediatamente">
    Não espere! Vá em **API Keys** ([/org-api-keys](https://app.gu1.ai/org-api-keys)) e revogue a key comprometida.
  </Step>

  <Step title="Crie Nova Key">
    Gere uma nova key com o mesmo nome + " (v2)" para identificação.
  </Step>

  <Step title="Atualize Sistemas">
    Substitua a key em todos os locais:

    * Variáveis de ambiente
    * Secret managers
    * Configurações de CI/CD
    * Documentação interna
  </Step>

  <Step title="Verifique Logs">
    Revise logs de uso da key comprometida:

    * Houve acesso não autorizado?
    * Quais dados foram acessados?
    * Precisa notificar clientes?
  </Step>

  <Step title="Investigue a Origem">
    Como a key foi exposta?

    * Commit no Git público?
    * Compartilhada por acidente?
    * Phishing?
    * Dispositivo roubado?
  </Step>

  <Step title="Previna Recorrência">
    Implemente medidas preventivas:

    * Git secrets scanning
    * Treinamento de segurança
    * Rotação automática
    * Secret managers obrigatórios
  </Step>
</Steps>

## Exemplos de Integração

### Webhook Receiver

```javascript theme={null}
// 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

```python theme={null}
# 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

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/pt/api-reference/authentication">
    Documentação completa da API REST
  </Card>

  <Card title="SDK do gu1" icon="code" href="/pt/api-reference/authentication">
    Bibliotecas JavaScript, Python, Ruby, PHP
  </Card>

  <Card title="Webhooks" icon="webhook" href="/pt/webhooks/configuration">
    Configure notificações em tempo real
  </Card>

  <Card title="Exemplos de Código" icon="laptop-code" href="/pt/api-reference/integrations/provider-codes">
    Integrações prontas (Zapier, n8n, Make)
  </Card>
</CardGroup>

## Precisa de Ajuda?

* **Documentação**: Navegue por nossas guias completas
* **Email**: [support@gueno.com](mailto:support@gueno.com)
* **Dashboard**: Acesse sua conta em [app.gu1.ai](https://app.gu1.ai)
* **Status da API**: [status.gu1.ai](https://status.gu1.ai)

***

**Última atualização**: Janeiro 2025