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

# Quick Start

> Do cadastro do app ao primeiro envio com access token — painel ou API.

<Tip>
  Objetivo: **registrar o app → usuário aprovar no browser → chamar `/v1` com Bearer token**. Prefere interface? Comece em **Developer → OAuth Apps**.
</Tip>

## Em poucas palavras

* **Cliente OAuth** = cadastro do seu app (nome, redirect, escopos).
* **PKCE** = proteção extra no fluxo pelo browser (obrigatório).
* **Access token** = crachá JWT \~15 min; **refresh token** = renova sem novo login.

Contexto: [Introdução](/oauth-api/como-funciona/introducao) · Escopos: [Escopos](/oauth-api/como-funciona/escopos)

## Antes de começar

* Conta Notifique com acesso ao workspace desejado
* **Redirect URI** exata (ex.: `https://meuapp.com/oauth/callback`)
* Escopo mínimo (ex.: `email:send` para testar e-mail)
* Base URL: `https://api.notifique.dev`

***

## 1. Registrar o cliente

Escolha **painel** ou **API**:

#### 1A, Pelo painel

1. **Developer → OAuth Apps → Criar app**
2. Nome, redirect URIs e escopos
3. Copie **Client ID** e **Client Secret** (secret só aparece uma vez)

#### 1B, Pela API

Cadastra o app programaticamente — útil para MCP e automação.

```http theme={null}
POST /oauth/register
Content-Type: application/json
```

```json theme={null}
{
  "client_name": "Meu App",
  "redirect_uris": ["https://meuapp.com/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "client_secret_basic",
  "scope": "email:send"
}
```

Resposta esperada: **201** com `client_id` e, se confidencial, `client_secret`.

<Note>
  CLI local sem secret: `"token_endpoint_auth_method": "none"` e redirect `http://127.0.0.1:<porta>/callback`.
</Note>

***

## 2. Preparar PKCE e abrir o browser

Gere antes de redirecionar:

* `code_verifier` — string aleatória (43–128 caracteres)
* `code_challenge` — Base64 URL-safe de SHA-256 do verifier (`S256`)
* `state` — aleatório; valide no callback

Abra no browser (substitua os valores):

```
https://api.notifique.dev/oauth/authorize
  ?client_id=SEU_CLIENT_ID
  &response_type=code
  &redirect_uri=https://meuapp.com/oauth/callback
  &scope=email:send
  &state=VALOR_ALEATORIO
  &code_challenge=SEU_CODE_CHALLENGE
  &code_challenge_method=S256
```

O usuário faz login, escolhe o workspace e aprova. Volta com `?code=...&state=...`. Troque o `code` logo — expira em minutos.

***

## 3. Trocar o code por tokens

Cliente **confidencial** (com secret):

```http theme={null}
POST /oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64(client_id:client_secret)
```

```
grant_type=authorization_code
&code=CODIGO_DO_REDIRECT
&redirect_uri=https://meuapp.com/oauth/callback
&code_verifier=SEU_CODE_VERIFIER
```

Cliente **público**: mesmo body, sem header `Authorization`.

Resposta esperada: **200** com `access_token`, `refresh_token` e `expires_in` (\~900 s).

***

## 4. Chamar a API

Substitua a API Key pelo access token:

```http theme={null}
POST /v1/email/messages
Authorization: Bearer eyJ...
Content-Type: application/json
```

```json theme={null}
{
  "from": "Suporte <noreply@seudominio.com>",
  "to": ["cliente@exemplo.com"],
  "subject": "Olá via OAuth",
  "text": "Primeiro envio com OAuth 2.1."
}
```

Resposta esperada: **200** — mensagem na fila. Domínio do `from` precisa estar verificado (igual ao fluxo com API Key).

***

## Depois do primeiro request

* **Renovar:** `POST /oauth/token` com `grant_type=refresh_token` — salve sempre o refresh **novo**
* **Revogar:** `POST /oauth/revoke` ou painel **Apps conectados**
* **Detalhes:** [Guia técnico](/oauth-api/como-funciona/guia-tecnico-cliente) · [OpenAPI](/oauth-api/api-reference/openapi-oauth.json) na aba **Outros**