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

# Autenticação

> Como autenticar suas requisições na API MessageFy

# Autenticação

A API MessageFy utiliza **API Keys** para autenticação. Todas as requisições passam pelo gateway
APISIX, que valida a chave e injeta headers de contexto automaticamente.

<Note>
  Esta página trata da **autenticação da API REST** (a chave que assina cada requisição HTTP).
  Isso é diferente da **conexão/autenticação do dispositivo WhatsApp** (parear o número ao canal),
  feita por QR Code, Pair Code, Link, Importação de Sessão ou Passkey. Para conectar um número,
  consulte [Iniciar Sessão](/comandos/iniciar-sessao),
  [Importar Sessão](/comandos/importar-sessao) e [Confirmar Passkey](/comandos/confirmar-passkey).
</Note>

## Como funciona

<Steps>
  <Step title="Obtenha sua API Key">
    Crie uma API Key pelo painel administrativo ou pela API (`POST /api/v1/Admin/ApiKey`).
    A chave está vinculada a uma conta e organização específicas.
  </Step>

  <Step title="Envie no header X-API-KEY">
    Inclua a chave no header `X-API-KEY` de todas as requisições.
  </Step>

  <Step title="Gateway injeta o contexto">
    O APISIX valida a chave e adiciona automaticamente os headers de identidade
    na requisição que chega ao backend.
  </Step>
</Steps>

## Tipos de Chave

A abrangência de acesso de uma chave é definida pelo **tipo da chave**, identificado pelo prefixo:

| Prefixo | Abrangência                                         |
| ------- | --------------------------------------------------- |
| `org_`  | Acesso a toda a **Organization** (todas as contas). |
| `acc_`  | Acesso a uma única **Account**.                     |

O limite de uso é controlado pelo `ResourcePlan` associado à chave (rate limit), não por permissões
granulares. Consulte [Administrando API Keys](/api-keys/introducao) para detalhes.

## Exemplo de Requisição

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-dev.messagefy.io/api/v1/message/SendMessage \
    -H "Content-Type: application/json" \
    -H "X-API-KEY: sua-api-key-aqui" \
    -d '{
      "channelId": "seu-channel-id",
      "content": {
        "type": "TEXT",
        "to": {
          "type": "WHATSAPP",
          "number": "5511999999999"
        },
        "text": "Olá!"
      }
    }'
  ```

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

  response = requests.post(
      "https://api-dev.messagefy.io/api/v1/message/SendMessage",
      headers={
          "Content-Type": "application/json",
          "X-API-KEY": "sua-api-key-aqui"
      },
      json={
          "channelId": "seu-channel-id",
          "content": {
              "type": "TEXT",
              "to": {
                  "type": "WHATSAPP",
                  "number": "5511999999999"
              },
              "text": "Olá!"
          }
      }
  )
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api-dev.messagefy.io/api/v1/message/SendMessage",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-KEY": "sua-api-key-aqui",
      },
      body: JSON.stringify({
        channelId: "seu-channel-id",
        content: {
          type: "TEXT",
          to: {
            type: "WHATSAPP",
            number: "5511999999999",
          },
          text: "Olá!",
        },
      }),
    }
  );
  const data = await response.json();
  console.log(data);
  ```

  ```csharp C# theme={null}
  using var client = new HttpClient();
  client.DefaultRequestHeaders.Add("X-API-KEY", "sua-api-key-aqui");

  var payload = new
  {
      channelId = "seu-channel-id",
      content = new
      {
          type = "TEXT",
          to = new { type = "WHATSAPP", number = "5511999999999" },
          text = "Olá!"
      }
  };

  var response = await client.PostAsJsonAsync(
      "https://api-dev.messagefy.io/api/v1/message/SendMessage",
      payload
  );
  var result = await response.Content.ReadAsStringAsync();
  Console.WriteLine(result);
  ```
</CodeGroup>

## Headers Injetados pelo Gateway

Após a validação da API Key, o gateway APISIX injeta estes headers automaticamente:

| Header                         | Tipo   | Descrição                         |
| ------------------------------ | ------ | --------------------------------- |
| `X-Consumer-Organization-Id`   | UUID   | Identificador da organização      |
| `X-Consumer-Organization-Name` | string | Nome da organização               |
| `X-Consumer-Account-Id`        | UUID   | Identificador da conta            |
| `X-Consumer-Account-Name`      | string | Nome da conta                     |
| `X-Consumer-Region`            | string | Região do consumidor              |
| `X-Request-Id`                 | UUID   | Identificador único da requisição |

<Warning>
  Estes headers são gerenciados pelo gateway. **Não envie manualmente** — eles serão
  sobrescritos pela validação da API Key.
</Warning>

## Rate Limiting

Cada API Key pode ter um plano de recursos (`ResourcePlan`) associado que define
limites de uso. Quando o limite é atingido, a API retorna `429 Too Many Requests`.

## Erros de Autenticação

| Status                  | Descrição                                                                                                                                                                                       |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized`      | API Key inválida, expirada ou ausente -- **e também** quando a chave é válida mas o recurso está fora da abrangência dela (`org_`/`acc_`). A API usa `401` (não `403`) para violações de escopo |
| `404 Not Found`         | Retornado em alguns casos de escopo para não revelar a existência do recurso (ex.: chave de conta consultando uma API Key de organização)                                                       |
| `429 Too Many Requests` | Limite de uso excedido                                                                                                                                                                          |

```json Exemplo de erro 401 theme={null}
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
  "title": "Unauthorized",
  "status": 401
}
```