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

# Autenticação

> OAuth 2.0 e tokens JWT bearer para a API e o servidor MCP da iZap.

Tanto a API REST quanto o servidor MCP são protegidos pelo mesmo servidor de
autorização OAuth 2.0, montado em `{origin}/oauth`. Cada requisição carrega um JWT
como Bearer token.

## Token rápido (servidor-a-servidor)

Para serviços de backend e scripts, troque as credenciais da conta por um JWT:

```bash theme={null}
curl -X POST "https://api.izap.ai/api/v1/auth/jwt/login" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "username=$IZAP_EMAIL&password=$IZAP_PASSWORD"
# -> {"access_token":"<JWT>","token_type":"bearer"}
```

Depois, envie-o em cada requisição:

```
Authorization: Bearer <access_token>
```

## OAuth 2.0 (aplicações de terceiros)

Use o fluxo authorization-code + PKCE para clientes que agem em nome de um usuário.

### Descoberta

Os clientes descobrem o servidor de autorização por meio de documentos de metadados
padrão:

| Documento                            | Caminho                                     |
| ------------------------------------ | ------------------------------------------- |
| Metadados do servidor de autorização | `/.well-known/oauth-authorization-server`   |
| Metadados do recurso protegido (MCP) | `/.well-known/oauth-protected-resource/mcp` |

O endpoint MCP retorna `401` com um header `WWW-Authenticate`, então clientes MCP
compatíveis com a especificação inicializam o fluxo OAuth automaticamente.

### Fluxo

1. `GET /oauth/authorize` com `response_type=code`, `client_id`, `redirect_uri`,
   `code_challenge`, `code_challenge_method=S256` e `state`.
2. O usuário se autentica e aprova; a iZap redireciona de volta com `code`.
3. `POST /oauth/token` com `grant_type=authorization_code`, `code`,
   `redirect_uri` e `code_verifier` → retorna um `access_token` (JWT) e um
   `refresh_token`.

Clientes públicos podem se autorregistrar via `POST /oauth/register`. Renove um
token expirado com `grant_type=refresh_token`.

## Notas sobre tokens

* O token de acesso é um JWT — trate-o como um segredo e leia-o a partir de uma
  variável de ambiente, nunca o deixe fixo no código.
* Os tokens expiram. Renove-os (fazendo login novamente ou via OAuth refresh grant)
  quando uma requisição retornar `401`.