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

# Autenticação

> Aprenda como autenticar com a API gu1 usando chaves API — para a API REST da gu1 usando chaves de API e tokens bearer, com exemplos para authentication.

## 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](#formato-da-chave-api)).

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

<Warning>
  Mantenha suas chaves API seguras! Nunca as envie para controle de versão ou compartilhe publicamente.
</Warning>

## Obtendo sua chave API

<Steps>
  <Step title="Fazer login no Dashboard">
    Navegue até [app.gu1.ai](https://app.gu1.ai) e faça login em sua conta
  </Step>

  <Step title="Acessar seção de chaves API">
    Clique em **Configurações** → **Chaves API** na barra lateral
  </Step>

  <Step title="Criar nova chave">
    Clique no botão **Criar chave API**
  </Step>

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

  <Step title="Copiar e armazenar">
    Copie a chave gerada imediatamente - ela será mostrada apenas uma vez!
  </Step>
</Steps>

## Usando sua chave API

Inclua sua chave API no cabeçalho `Authorization` de cada solicitação:

```bash theme={null}
curl http://api.gu1.ai/entities \
  -H "Authorization: Bearer gk_prod_SUA_CHAVE_AQUI"
```

### Exemplo com diferentes métodos

<CodeGroup>
  ```bash cURL theme={null}
  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"}'
  ```

  ```javascript JavaScript / Node.js theme={null}
  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'
    })
  });
  ```

  ```python Python theme={null}
  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
  )
  ```
</CodeGroup>

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

<Note>
  Aplique o menor privilégio: preferência por concessões explícitas `recurso:ação` em vez de acesso amplo.
</Note>

## Melhores práticas

<AccordionGroup>
  <Accordion icon="lock" title="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`)
  </Accordion>

  <Accordion icon="rotate" title="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
  </Accordion>

  <Accordion icon="shield-halved" title="Monitorar uso">
    * Revise regularmente a atividade das chaves API no dashboard
    * Configure alertas para padrões de uso incomuns
    * Revogue imediatamente chaves comprometidas
  </Accordion>

  <Accordion icon="code-branch" title="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
  </Accordion>
</AccordionGroup>

## Respostas de erro

Se a autenticação falhar, você receberá uma destas respostas de erro:

### Chave API ausente

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "No API key provided"
  }
}
```

**Status HTTP:** `401 Unauthorized`

### Chave API inválida

```json theme={null}
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key provided"
  }
}
```

**Status HTTP:** `401 Unauthorized`

### Chave API expirada

```json theme={null}
{
  "error": {
    "code": "EXPIRED_API_KEY",
    "message": "API key has expired"
  }
}
```

**Status HTTP:** `401 Unauthorized`

### Permissões insuficientes

```json theme={null}
{
  "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:

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

```json theme={null}
{
  "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:**

```http theme={null}
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2025-01-15T10:00:00Z
Retry-After: 3600
```

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

## Testando sua chave API

Use este teste simples para verificar se sua chave API está funcionando:

```bash theme={null}
curl http://api.gu1.ai/auth/test \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Resposta de sucesso:**

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

<CardGroup cols={2}>
  <Card title="Criar sua primeira entidade" icon="building" href="/pt/api-reference/entities/create">
    Comece a usar a API para criar entidades
  </Card>

  <Card title="Definir esquemas personalizados" icon="table" href="/pt/api-reference/data-ingestion/custom-schemas">
    Configure o mapeamento de dados para seu caso de uso
  </Card>

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

  <Card title="Fluxo KYC completo" icon="book" href="/pt/use-cases/kyc/fluxo-completo">
    Guia de integração KYC ponta a ponta
  </Card>
</CardGroup>