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

# Autenticação

> Como autenticar suas requisições na Wapizap API

# Autenticação

A Wapizap API usa **Bearer Token** (API Keys) para autenticar requisições. Todas as requisições devem incluir sua API Key no header `Authorization`.

## Obtendo sua API Key

<Steps>
  <Step title="Acessar o Dashboard">
    Faça login em [dashboard.wapizap.com](https://dashboard.wapizap.com)
  </Step>

  <Step title="Navegar até API Keys">
    Vá em **Configurações → API Keys** no menu lateral
  </Step>

  <Step title="Gerar Nova Chave">
    Clique em **Gerar Nova API Key**

    Você será solicitado a:

    * Dar um nome para a chave (ex: "Produção", "Desenvolvimento")
    * Escolher as permissões (opcional)
  </Step>

  <Step title="Copiar e Guardar">
    ⚠️ **IMPORTANTE:** A chave é exibida **apenas uma vez**

    Copie imediatamente e guarde em local seguro (ex: variáveis de ambiente)
  </Step>
</Steps>

***

## Formato da API Key

As API Keys da Wapizap seguem este formato:

```
sk_live_1234567890abcdefghijklmnopqrstuvwxyz
     ↑        ↑
  ambiente  identificador único
```

### Ambientes

| Prefixo    | Ambiente | Uso                          |
| ---------- | -------- | ---------------------------- |
| `sk_live_` | Produção | Dados reais, cobrança ativa  |
| `sk_test_` | Teste    | Dados de teste, sem cobrança |

<Warning>
  **Nunca** exponha suas chaves `sk_live_` publicamente. Use variáveis de ambiente!
</Warning>

***

## Como Usar

Inclua sua API Key no header `Authorization` com o prefixo `Bearer`:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.wapizap.com/api/v2/instances \
    -H "Authorization: Bearer sk_live_SEU_TOKEN_AQUI"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.wapizap.com/api/v2/instances', {
    headers: {
      'Authorization': 'Bearer sk_live_SEU_TOKEN_AQUI'
    }
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.wapizap.com/api/v2/instances',
      headers={
          'Authorization': 'Bearer sk_live_SEU_TOKEN_AQUI'
      }
  )
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://api.wapizap.com/api/v2/instances');

  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer sk_live_SEU_TOKEN_AQUI'
  ]);

  $response = curl_exec($ch);
  ?>
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
  )

  func main() {
      req, _ := http.NewRequest("GET", "https://api.wapizap.com/api/v2/instances", nil)
      req.Header.Set("Authorization", "Bearer sk_live_SEU_TOKEN_AQUI")

      client := &http.Client{}
      resp, _ := client.Do(req)
  }
  ```
</CodeGroup>

***

## Variáveis de Ambiente

<Tip>
  **Melhor prática:** Sempre use variáveis de ambiente para armazenar API Keys
</Tip>

### Node.js (com dotenv)

```bash .env theme={null}
WAPIZAP_API_KEY=sk_live_1234567890abcdef
```

```javascript index.js theme={null}
require('dotenv').config();

const apiKey = process.env.WAPIZAP_API_KEY;

fetch('https://api.wapizap.com/api/v2/instances', {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});
```

### Python (com python-dotenv)

```bash .env theme={null}
WAPIZAP_API_KEY=sk_live_1234567890abcdef
```

```python main.py theme={null}
import os
from dotenv import load_dotenv

load_dotenv()

api_key = os.getenv('WAPIZAP_API_KEY')

requests.get(
    'https://api.wapizap.com/api/v2/instances',
    headers={'Authorization': f'Bearer {api_key}'}
)
```

### PHP

```php theme={null}
<?php
// Usando variável de ambiente do servidor
$apiKey = getenv('WAPIZAP_API_KEY');

$ch = curl_init('https://api.wapizap.com/api/v2/instances');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer {$apiKey}"
]);
?>
```

***

## Erros de Autenticação

### 401 Unauthorized - Token Inválido

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

**Causas comuns:**

* API Key incorreta ou mal formatada
* Falta do prefixo `Bearer` no header
* Chave expirada ou revogada

### 401 Unauthorized - Token Ausente

```json theme={null}
{
  "success": false,
  "error": {
    "code": "MISSING_AUTH",
    "message": "Authorization header is required"
  }
}
```

**Solução:** Certifique-se de incluir o header `Authorization` em todas as requisições.

### 403 Forbidden - Permissões Insuficientes

```json theme={null}
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "This API key does not have permission to perform this action"
  }
}
```

**Solução:** Verifique as permissões da sua API Key no dashboard.

***

## Gerenciamento de API Keys

### Listar API Keys

No dashboard, você pode ver todas as suas chaves ativas:

* Nome da chave
* Data de criação
* Último uso
* Permissões
* Número de requisições (últimas 24h)

### Revogar API Key

<Warning>
  **Atenção:** Revogar uma chave é **irreversível** e quebrará todas as integrações que a utilizam!
</Warning>

Para revogar uma chave:

1. Acesse **Configurações → API Keys**
2. Clique nos 3 pontinhos ao lado da chave
3. Selecione **Revogar**
4. Confirme a ação

### Rotação de Chaves

Recomendamos rotacionar suas API Keys periodicamente (ex: a cada 90 dias):

1. Gere uma nova API Key
2. Atualize suas aplicações com a nova chave
3. Teste se tudo funciona
4. Revogue a chave antiga

***

## Permissões de API Key

Ao criar uma API Key, você pode definir permissões granulares:

| Permissão  | Descrição                                                    |
| ---------- | ------------------------------------------------------------ |
| **read**   | Listar e visualizar recursos (instâncias, mensagens, grupos) |
| **write**  | Criar e atualizar recursos                                   |
| **delete** | Deletar recursos                                             |
| **admin**  | Acesso total incluindo configurações da conta                |

### Exemplo de Permissões

```json theme={null}
{
  "permissions": {
    "instances": ["read", "write"],
    "messages": ["read", "write"],
    "groups": ["read", "write"],
    "webhooks": ["read", "write", "delete"],
    "settings": [] // Sem acesso
  }
}
```

<Tip>
  **Princípio do Menor Privilégio:** Conceda apenas as permissões necessárias para cada chave.
</Tip>

***

## Segurança

### ✅ Boas Práticas

<Check>Use variáveis de ambiente em vez de hardcode</Check>
<Check>Nunca commite API Keys no Git</Check>
<Check>Use chaves diferentes para dev/staging/prod</Check>
<Check>Rotacione chaves periodicamente</Check>
<Check>Revogue chaves imediatamente se comprometidas</Check>
<Check>Use HTTPS em todas as requisições</Check>
<Check>Implemente rate limiting no seu lado</Check>

### ❌ Evite

<Warning>Expor chaves em código frontend/mobile</Warning>
<Warning>Compartilhar chaves entre projetos/times</Warning>
<Warning>Logar API Keys em arquivos de log</Warning>
<Warning>Enviar chaves por email/chat</Warning>
<Warning>Usar a mesma chave para dev e produção</Warning>

### Arquivo .gitignore

Sempre adicione arquivos de configuração ao `.gitignore`:

```bash .gitignore theme={null}
# Environment variables
.env
.env.local
.env.*.local

# API Keys
**/config/secrets.js
**/config/credentials.json
```

***

## Rate Limiting

A API aplica rate limiting por API Key:

| Tier       | Requisições por Minuto |
| ---------- | ---------------------- |
| Free       | 60                     |
| Starter    | 120                    |
| Pro        | 300                    |
| Enterprise | Personalizado          |

### Headers de Rate Limit

Cada resposta inclui headers informativos:

```http theme={null}
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1705233060
```

| Header                  | Descrição                   |
| ----------------------- | --------------------------- |
| `X-RateLimit-Limit`     | Limite total de requisições |
| `X-RateLimit-Remaining` | Requisições restantes       |
| `X-RateLimit-Reset`     | Timestamp Unix do reset     |

### 429 Too Many Requests

Quando o limite é excedido:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry after 60 seconds.",
    "retryAfter": 60
  }
}
```

<Info>
  Implemente **exponential backoff** para lidar com rate limits automaticamente.
</Info>

***

## Testando Autenticação

Faça um teste rápido para verificar se sua autenticação está funcionando:

```bash theme={null}
curl -X GET https://api.wapizap.com/api/v2/instances \
  -H "Authorization: Bearer sk_live_SEU_TOKEN_AQUI"
```

**Resposta de sucesso (200):**

```json theme={null}
{
  "success": true,
  "data": []
}
```

**Se retornar 401:** Verifique se sua API Key está correta e no formato `Bearer sk_live_...`

***

## Próximos Passos

Agora que você entende autenticação:

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Crie sua primeira instância
  </Card>

  <Card title="API Reference" icon="book" href="/api-v2/overview">
    Explore todos os endpoints
  </Card>
</CardGroup>

***

## Precisa de Ajuda?

<Card title="Suporte" icon="headset" href="mailto:support@wapizap.com">
  Se tiver problemas com autenticação, entre em contato: [support@wapizap.com](mailto:support@wapizap.com)
</Card>