Introdução/Autenticação

Autenticação

Como autenticar suas requisições na TurboZap API

Visão geral

A TurboZap API utiliza API Keys para autenticação. Cada instância criada recebe uma API Key única que deve ser enviada em todas as requisições relacionadas àquela instância.

API Key por Instância

Quando você cria uma instância, a API retorna uma API Key única. Use essa chave para todas as operações naquela instância (mensagens, grupos, etc).

Usando a API Key

Ao criar uma instância, você receberá uma resposta como esta:

Resposta da criação de instância

{
  "success": true,
  "data": {
    "instance": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "minha-instancia",
      "api_key": "550e8400-e29b-41d4-a716-446655440000-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "disconnected",
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  }
}

Importante

Guarde sua API Key em um local seguro! Ela é mostrada apenas uma vez durante a criação da instância. Se você perder, precisará criar uma nova instância.

Headers de autenticação

Existem duas formas de enviar sua API Key:

Opção 1: Header X-API-Key (Recomendado)

Usando X-API-Key

curl --request POST \
  --url http://localhost:8080/message/minha-instancia/text \
  --header 'X-API-Key: sua-api-key-aqui' \
  --header 'Content-Type: application/json' \
  --data '{"to": "5511999999999", "text": "Olá!"}'

Opção 2: Header Authorization Bearer

Usando Authorization Bearer

curl --request POST \
  --url http://localhost:8080/message/minha-instancia/text \
  --header 'Authorization: Bearer sua-api-key-aqui' \
  --header 'Content-Type: application/json' \
  --data '{"to": "5511999999999", "text": "Olá!"}'

Erros de autenticação

401 Unauthorized

Retornado quando a API Key não é fornecida ou é inválida.

json

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key is required"
  }
}

403 Forbidden

Retornado quando a API Key não tem permissão para acessar o recurso.

json

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Invalid API key for this instance"
  }
}

Boas práticas

Use variáveis de ambiente

Nunca deixe sua API Key hardcoded no código. Use variáveis de ambiente como TURBOZAP_API_KEY.

Não exponha no frontend

A API Key deve ser usada apenas no backend. Nunca exponha ela em código JavaScript que roda no navegador.

Rotacione periodicamente

Se suspeitar que sua API Key foi comprometida, delete a instância e crie uma nova imediatamente.