> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.muchau.com.br/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.muchau.com.br/_mcp/server.

# Autenticação

> Como autenticar requisições à API com sua chave de API do Muchaw DEV.

## Chaves de API

O método de autenticação principal para todas as chamadas programáticas à API é uma **chave de API**.

### Formato

```
mk_live_<43 caracteres base64url>
```

Comprimento total: 51 caracteres. Exemplo:

```
mk_live_aB3xZ9mQwRtYpLkJnVdCeHfIoUsSgA7bWzXc4Eh
```

### Uso

Inclua a chave no header `Authorization` de cada requisição:

```http
Authorization: Bearer mk_live_<sua-chave>
```

### Criando chaves de API

No Dashboard → **Chaves de API** → **Criar Chave**, ou via API (requer uma sessão Clerk):

```bash
curl -X POST https://dev.muchau.com.br/api/auth/api-keys \
  -H "Authorization: Bearer <CLERK_SESSION_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "production" }'
```

> **Warning**
>
> A chave completa é exibida **apenas uma vez** no momento da criação. Ela não pode ser recuperada depois.
> Armazene-a imediatamente em um gerenciador de secrets ou arquivo `.env`.

### Revogando chaves de API

Chaves podem ser revogadas no Dashboard ou via `DELETE /api/auth/api-keys/:id`. Chaves revogadas são rejeitadas imediatamente.

---

## Tokens de Sessão Clerk (apenas Dashboard)

Um segundo método de autenticação — JWTs do Clerk — é usado apenas pelo frontend do Dashboard para gerenciar a conta (criar/revogar chaves de API, visualizar informações da conta). Esses tokens são emitidos pelo [Clerk](https://clerk.com) e não se destinam ao uso direto via API.

Se você está construindo integrações, sempre use chaves de API.

---

## Limites de Taxa

| Plano   | Requisições por minuto |
| ------- | ---------------------- |
| Starter | 100                    |
| Pro     | 500                    |

Informações sobre limite de taxa são retornadas nos headers da resposta:

```http
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1720000060
```

Quando o limite é excedido, a API retorna `429 Too Many Requests`.

---

## Boas práticas de segurança

* Armazene chaves de API em variáveis de ambiente, nunca no código-fonte
* Use chaves separadas por ambiente (desenvolvimento, staging, produção)
* Rotacione chaves regularmente via Dashboard → Chaves de API → Rotacionar
* Configure allowlist de IPs para chaves de produção (em breve)

## Detalhes internos de implementação

* Chaves de API são armazenadas como hashes SHA-256 no banco de dados — a chave em texto simples nunca é persistida
* O prefixo da chave (`mk_live_XXXX`) (primeiros 12 caracteres) é armazenado apenas para fins de exibição
* Em cada requisição, o plugin `apiKeyGuard` extrai o Bearer token, aplica SHA-256 e busca o hash na tabela `api_keys`
* Se encontrado e não revogado (`revokedAt IS NULL`), a requisição é autenticada e `request.developer` é decorado com o registro do desenvolvedor
* `lastUsedAt` é atualizado de forma assíncrona (não bloqueia a resposta)
* O `authGuard` tenta a chave de API primeiro (se o header começar com `Bearer mk_live_`), depois recorre à sessão Clerk