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

# Autenticação

> Como autenticar na API da OctaSend com OAuth 2.0 Client Credentials: criar o OAuth Client, obter o access token e usá-lo nas chamadas

A API da OctaSend usa o padrão **OAuth 2.0 Client Credentials** (RFC 6749 §4.4) para integrações server-to-server. É a única forma de autenticação da plataforma: os antigos tokens permanentes que começavam com `msg_live_` foram desativados e não são mais aceitos.

O fluxo tem três partes:

**1. Crie um OAuth Client no painel**

Você recebe um `client_id` e um `client_secret` permanentes.

**2. Troque as credenciais por um access token**

Chame `POST /oauth-token`. O token vale por 1 hora.

**3. Use o token nas chamadas**

Envie `Authorization: Bearer <access_token>` em cada requisição à API.

## Base URL

Todos os endpoints desta referência ficam sob a mesma base. A API só aceita HTTPS.

```text theme={null}
https://api.octasend.com.br/functions/v1
```

## Criar um OAuth Client

No painel, acesse **Configurações → OAuth Clients**.

1. Digite um nome para identificar a integração (ex.: `Loja virtual – Produção`).
2. Clique em **Criar**.
3. Copie o `client_id` (começa com `client_`) e o `client_secret` (começa com `secret_`).

> [!WARNING]
>
> O `client_secret` aparece **uma única vez**, logo após a criação. Não é possível consultá-lo depois. Se perder, revogue o client e crie outro.

A lista de clients mostra:

| Coluna | O que significa |
| - | - |
| Nome | O nome que você deu ao client |
| client\_id | O identificador público, com botão para copiar |
| Escopos | Permissões do client. Hoje todo client recebe o escopo `send` |
| Último uso | Última vez que o client foi usado para autenticar |
| Status | **Ativo** ou **Inativo** (revogado) |

Qualquer usuário com acesso ao painel da conta pode criar e revogar OAuth Clients.

> [!TIP]
>
> Crie um client por ambiente ou por integração (desenvolvimento, homologação, produção, MCP). Assim, revogar um deles não derruba os outros.

### Revogar um client

Na linha do client, clique em **Revogar** e confirme. A revogação vale na hora:

* o client passa para **Inativo** e não pode ser reativado — para voltar a integrar, crie um client novo;
* todos os access tokens emitidos para ele deixam de funcionar imediatamente;
* o `client_id` também deixa de valer nos scripts que rodam no navegador (Web Push e widget In-App) e no webhook do Telegram configurado com essa credencial.

## Obter um access token

Veja o endpoint completo em [POST /oauth-token](https://docs.octasend.com.br/api-reference/oauth-token.md). O corpo pode ser JSON ou `application/x-www-form-urlencoded`.

```bash cURL theme={null}
curl -X POST https://api.octasend.com.br/functions/v1/oauth-token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "client_a3f8b2...",
    "client_secret": "secret_9e1c..."
  }'
```

```http form-urlencoded theme={null}
POST /functions/v1/oauth-token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=client_a3f8b2...&client_secret=secret_9e1c...
```

### Resposta

```json theme={null}
{
  "access_token": "at_f4a92b...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "send"
}
```

| Campo | Descrição |
| - | - |
| `access_token` | Token a enviar no header `Authorization`. Começa com `at_` |
| `token_type` | Sempre `Bearer` |
| `expires_in` | Validade em segundos (3600 = 1 hora) |
| `scope` | Escopos do client, separados por espaço (hoje, `send`) |

Cada chamada a `/oauth-token` emite um token novo; os anteriores continuam válidos até expirar. Guarde o token em cache e peça outro só perto do vencimento — os exemplos em [Enviar mensagens](https://docs.octasend.com.br/api-reference/enviar-mensagens.md#exemplos-por-linguagem) renovam 1 minuto antes.

> [!NOTE]
>
> O endpoint `/oauth-token` aceita até **30 pedidos por minuto por IP**. Acima disso, responde `429` com `{"error": "rate_limited", "retry_after": 60}` e o header `Retry-After`.

## Usar o token

Envie o access token no header `Authorization` de toda chamada:

```http theme={null}
POST /functions/v1/send-message
Authorization: Bearer at_f4a92b...
Content-Type: application/json
```

## Formas de apresentar a credencial

O mesmo OAuth Client pode ser usado de três formas, cada uma para um tipo de chamador:

| Forma | Onde usar | Exemplo de header |
| - | - | - |
| Access token (`at_...`) | Integração server-to-server com a API. **Forma recomendada** | `Authorization: Bearer at_f4a92b...` |
| Par `client_id:client_secret` | Chamadores que não conseguem manter um token em cache, como o [servidor MCP](https://docs.octasend.com.br/api-reference/mcp-server.md). Aceito pelos endpoints de envio, consulta de logs, listagem de comunicações, estatísticas, configuração de canal e disparo de automações | `Authorization: Bearer client_a3f8b2...:secret_9e1c...` |
| `client_id` sozinho | Scripts que rodam no navegador do seu cliente final: registro de [Web Push](https://docs.octasend.com.br/guias/web-push.md) e [widget In-App](https://docs.octasend.com.br/api-reference/widget-in-app.md). Com a verificação de identidade, o script envia também o `userHash` calculado no seu servidor | Depende do script |

No par `client_id:client_secret`, use dois-pontos sem espaços e cole os valores exatamente como aparecem no painel.

> [!NOTE]
>
> O `client_id` não é segredo: ele só identifica a sua conta. Sozinho, não autoriza envio de mensagens nem leitura do histórico. Já o `client_secret` dá acesso total à API e nunca deve ir para o navegador.
>
> Nos scripts do navegador, o `client_id` também não prova quem é o usuário. Para isso, ligue a verificação de identidade descrita em [Widget In-App](https://docs.octasend.com.br/api-reference/widget-in-app.md): o seu servidor assina o `userId` com um segredo da conta, e a mesma regra vale para o sino e para o registro do Web Push.

## Erros comuns

Erros do `/oauth-token`:

| HTTP | `error` | Causa | O que fazer |
| - | - | - | - |
| 400 | `unsupported_grant_type` | `grant_type` diferente de `client_credentials` | Envie `grant_type=client_credentials` |
| 400 | `invalid_request` | `client_id` ou `client_secret` ausente | Envie os dois campos |
| 401 | `invalid_client` | `client_id` inexistente, client revogado ou `client_secret` incorreto | Confira as credenciais e se o client está **Ativo** |
| 405 | `method_not_allowed` | Método diferente de `POST` | Use `POST` |
| 429 | `rate_limited` | Mais de 30 pedidos de token por minuto do mesmo IP | Aguarde `retry_after` segundos e reutilize o token em cache |
| 500 | `server_error` | Erro interno, inclusive corpo JSON malformado | Confira o corpo e tente de novo |

Erros de autenticação nos demais endpoints:

| HTTP | `error` | Causa | O que fazer |
| - | - | - | - |
| 401 | `Authorization header required. Use: Authorization: Bearer <token>` (envio de mensagens e disparo de automações) ou `Authorization header required` (consulta de logs) | Header `Authorization` ausente ou sem o prefixo `Bearer` | Envie o header no formato `Bearer <token>` |
| 401 | `Invalid, expired or revoked token` | Token vencido, client revogado ou par `client_id:client_secret` inválido (envio de mensagens, disparo de automações e consulta de logs) | Peça um novo token em `/oauth-token` e confira se o client está **Ativo** |

Os endpoints de listagem de comunicações, estatísticas de envio e configuração de canal respondem `401` com `{"error": "Unauthorized"}` nos dois casos: header ausente ou credencial inválida.

## Boas práticas de segurança

* **Nunca exponha** o `client_secret` nem o segredo de verificação de identidade no frontend (JavaScript do navegador, app mobile).
* **Guarde** as credenciais em variáveis de ambiente ou num cofre de segredos, fora do código.
* **Reutilize** o access token até perto da expiração, em vez de pedir um novo a cada envio.
* **Use HTTPS** em todas as chamadas.
* Se suspeitar de vazamento, **revogue** o client no painel e crie outro.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.