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

# Autenticação

> Como autenticar nas APIs do Vectax Hub

Todas as requisições protegidas requerem um Bearer token no header `Authorization`:

```
Authorization: Bearer YOUR_TOKEN
```

## Tipos de token

O Hub tem dois tipos de token com escopos diferentes:

<CardGroup cols={2}>
  <Card title="Token de Organização" icon="building">
    Acesso a todas as instâncias da organização. Precisa enviar `phone_number_id` no body ao enviar mensagens.
  </Card>

  <Card title="Token de Instância" icon="mobile">
    Vinculado a uma instância específica. O `phone_number_id` é resolvido automaticamente. Obrigatório para mídia, templates, QR codes, etc.
  </Card>
</CardGroup>

## Quando usar cada tipo

| Recurso           | Token de Org              | Token de Instância |
| ----------------- | ------------------------- | ------------------ |
| Enviar mensagens  | ✅ (com `phone_number_id`) | ✅ (automático)     |
| Upload de mídia   | ❌                         | ✅                  |
| Templates         | ❌                         | ✅                  |
| QR Codes          | ❌                         | ✅                  |
| Perfil da empresa | ❌                         | ✅                  |
| Analytics / WABA  | ✅                         | ✅                  |
| Webhooks          | ✅                         | ✅                  |
| Listar instâncias | ✅                         | ❌                  |

## Criando um token

### Via dashboard

1. Acesse **Configurações → API Tokens**
2. Clique em **Novo Token**
3. Dê um nome e, opcionalmente, selecione uma instância
4. Copie o token — ele só é exibido uma vez

### Via API

```bash theme={null}
curl -X POST https://apis.vectalk.com.br/api/auth/api-tokens \
  -H "Authorization: Bearer SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Minha Integração",
    "instance_id": "opcional-para-token-de-instancia"
  }'
```

**Resposta:**

```json theme={null}
{
  "id": "tok_...",
  "name": "Minha Integração",
  "token": "vectax_...",
  "instance_id": "inst_...",
  "created_at": "2026-01-01T00:00:00Z"
}
```

<Warning>
  O campo `token` é exibido **apenas uma vez** na criação. Armazene-o com segurança (variável de ambiente, secret manager, etc.).
</Warning>

## Listando e revogando tokens

```bash theme={null}
# Listar tokens
curl https://apis.vectalk.com.br/api/auth/api-tokens \
  -H "Authorization: Bearer YOUR_TOKEN"

# Revogar token
curl -X DELETE https://apis.vectalk.com.br/api/auth/api-tokens/TOKEN_ID \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Erros de autenticação

| Código             | Causa                                                                                                           |
| ------------------ | --------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | Token ausente, inválido ou expirado                                                                             |
| `403 Forbidden`    | Token válido, mas sem permissão para o recurso (ex: token de org tentando acessar endpoint que exige instância) |

```json theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized"
}
```