Autenticação

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:

Token de Organização

Acesso a todas as instâncias da organização. Precisa enviar phone_number_id no body ao enviar mensagens.

Token de Instância

Vinculado a uma instância específica. O phone_number_id é resolvido automaticamente. Obrigatório para mídia, templates, QR codes, etc.

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

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

Via API

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:

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

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

Listando e revogando tokens

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

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Primeiros Passos

Conceitos

Tipos de token

Token de Organização

Token de Instância

Quando usar cada tipo

Criando um token

Via dashboard

Via API

Listando e revogando tokens

Erros de autenticação

​Tipos de token

Token de Organização

Token de Instância

​Quando usar cada tipo

​Criando um token

​Via dashboard

​Via API

​Listando e revogando tokens

​Erros de autenticação

Tipos de token

Quando usar cada tipo

Criando um token

Via dashboard

Via API

Listando e revogando tokens

Erros de autenticação