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

# OAuth 2.0

> Authorization Code + PKCE para integrações de terceiros na API pública /v1

OAuth 2.0 permite que **aplicações de terceiros** acessem a API pública `/v1/*` em nome de uma conta merchant que autorizou o acesso. É diferente da [chave de API](/pages/guides/authentication): a chave é server-to-server da própria conta; OAuth é consentimento do titular da conta.

<Note>
  OAuth2 puro — **sem** OpenID Connect. Identidade da conta: [GET /v1/me](/api-reference/endpoint/account/me) com scope `account:read`. Não há `/oauth/userinfo`.
</Note>

## Pré-requisitos

1. Conta merchant com **API pública habilitada** (solicite ao suporte GoatPay se necessário).
2. Aplicação registrada via [API `/v1/oauth-apps`](/api-reference/guides/oauth-apps) ou em **Integrações → Aplicações OAuth** no [dashboard](https://app.goatpay.com.br/dashboard/integrations/developer).
3. Credenciais **DEV** e **PRODUCTION** separadas (`client_id` + `client_secret` por ambiente).
4. Redirect URIs cadastradas com **match exato** (sem wildcards). HTTPS em produção; `http://localhost` em DEV; schemes custom (`myapp://callback`) permitidos se registrados explicitamente.

## Descoberta automática

Consulte [GET /.well-known/oauth-authorization-server](/api-reference/endpoint/oauth/well-known) para obter `authorization_endpoint`, `token_endpoint`, `revocation_endpoint` e `scopes_supported`.

## Fluxo completo

```text theme={null}
Sua app → GET /oauth/authorize (+ PKCE S256 + state)
       → Login + consentimento (app.goatpay.com.br/oauth/consent)
       → redirect_uri?code=...&state=...
       → POST /oauth/token (code + code_verifier)
       → access_token + refresh_token
       → Authorization: Bearer gp_oat_live_... nas rotas /v1/*
```

<Steps>
  <Step title="1. Criar aplicação">
    [POST /oauth-apps/create](/api-reference/endpoint/oauth-apps/create) ou dashboard → **Aplicações OAuth** → nome, descrição e scopes. Gere credenciais DEV e Production; o `client_secret` aparece **uma vez**.
  </Step>

  <Step title="2. Redirect URI">
    Ex.: `https://sua-app.com/oauth/callback` (produção), `http://localhost:3000/oauth/callback` (DEV) ou `myapp://oauth/callback` (app mobile, se registrado).
  </Step>

  <Step title="3. PKCE">
    Gere `code_verifier` e `code_challenge` (S256). Guarde o verifier no servidor; envie apenas o challenge no authorize.
  </Step>

  <Step title="4. Autorizar">
    Redirecione para [GET /oauth/authorize](/api-reference/endpoint/oauth/authorize).
  </Step>

  <Step title="5. Token">
    Valide `state` no callback e troque o `code` em [POST /oauth/token](/api-reference/endpoint/oauth/token).
  </Step>

  <Step title="6. API">
    Use `Authorization: Bearer gp_oat_live_...` nas rotas `/v1/*` dentro dos scopes aprovados.
  </Step>
</Steps>

## Consentimento

Após `/oauth/authorize`, o usuário vê em `app.goatpay.com.br/oauth/consent`:

* Nome, logo e desenvolvedor da aplicação
* Scopes solicitados com descrições
* Links para site, privacidade e termos (quando cadastrados)

O usuário pode aprovar ou negar. Em caso de negação, o redirect traz `error=access_denied`.

## PKCE (obrigatório)

| Parâmetro                    | Onde                   |
| ---------------------------- | ---------------------- |
| `code_challenge`             | `GET /oauth/authorize` |
| `code_challenge_method=S256` | `GET /oauth/authorize` |
| `code_verifier`              | `POST /oauth/token`    |

```javascript theme={null}
import { createHash, randomBytes } from "crypto";

const verifier = randomBytes(32).toString("base64url");
const challenge = createHash("sha256").update(verifier).digest("base64url");
```

```python theme={null}
import hashlib, base64, secrets

verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b"=").decode()
challenge = base64.urlsafe_b64encode(
    hashlib.sha256(verifier.encode()).digest()
).rstrip(b"=").decode()
```

## Cadeia de scopes

```text theme={null}
Scopes solicitados no authorize
  → Interseção com os permitidos na aplicação
  → Scopes aprovados no consentimento
  → Scopes persistidos na autorização
  → Scopes do access token
  → Permissões efetivas em /v1/*
```

O token **nunca** recebe scope maior que o aprovado pelo usuário.

| Scope                | Acesso na API                                |
| -------------------- | -------------------------------------------- |
| `account:read`       | Saldo, extrato, `GET /v1/me`                 |
| `account:write`      | Alterar configurações da conta *(reservado)* |
| `transactions:read`  | Listar PIX, transferências, estornos         |
| `transactions:write` | Criar transferências e estornos              |
| `payments:read`      | Consultar cobranças PIX                      |
| `payments:write`     | Criar cobranças PIX                          |
| `withdrawals:read`   | Consultar payouts                            |
| `withdrawals:create` | Criar payouts                                |
| `webhooks:read`      | Listar webhooks                              |
| `webhooks:write`     | CRUD webhooks                                |

## Limites do OAuth vs API key

OAuth cobre operações de conta, PIX, transferências, payouts e webhooks dentro dos scopes acima. **Não** está disponível via OAuth (use API key da própria conta):

* Pagamentos e transferências **cripto**
* Loja (`customers`, `products`, `coupons`, `payment-links`)
* Cobranças recorrentes (`billings`, `subscriptions`)
* Subcontas (`subaccount/*`)

Consulte [escopo da API pública](/api-reference/escopo-api-publica) para o mapa completo.

## Identidade da conta

```bash theme={null}
curl https://api.goatpay.com.br/v1/me \
  -H "Authorization: Bearer gp_oat_live_..."
```

Documentação: [GET /v1/me](/api-reference/endpoint/account/me). Retorna a **conta merchant autorizada**, não o perfil pessoal de quem autorizou.

## Webhooks

Apps OAuth com scopes `webhooks:read` e `webhooks:write` podem cadastrar endpoints em `/v1/webhooks/*` com bearer `gp_oat_*`. Eventos de lifecycle OAuth (`oauth.authorization.*`, `oauth.application.*`, `oauth.client.*`) são entregues ao dono da aplicação e/ou à conta autorizada — veja o [guia de webhooks](/api-reference/guides/webhooks#oauth-20).

## Renovar e revogar

* **Refresh:** `grant_type=refresh_token` em [POST /oauth/token](/api-reference/endpoint/oauth/token) — o refresh anterior é invalidado (rotação).
* **Revogar:** [POST /oauth/revoke](/api-reference/endpoint/oauth/revoke) com `token=...`.

Access tokens expiram em **15 minutos**. Armazene refresh tokens com segurança no servidor.

## Erros comuns

### No redirect (`/oauth/authorize`)

| `error`          | Ação                                      |
| ---------------- | ----------------------------------------- |
| `access_denied`  | Usuário cancelou — trate na UI            |
| `invalid_scope`  | Scope não permitido na aplicação          |
| `invalid_client` | Verifique `client_id` e ambiente DEV/PROD |

### Na API (`/v1/*` com bearer)

| HTTP | `error`              | Ação                                              |
| ---- | -------------------- | ------------------------------------------------- |
| 401  | `invalid_token`      | Token expirado ou revogado — renove ou reautorize |
| 403  | `insufficient_scope` | Peça scopes adicionais no authorize               |

Rotas `/oauth/*` usam erros RFC 6749 (`invalid_grant`, etc.) sem envelope `{ success, data }` — veja [guia de erros](/api-reference/guides/errors#oauth-20).

## Boas práticas

* `client_secret` **somente no servidor** — nunca no frontend ou app mobile
* Gere e valide `state` no callback (CSRF)
* Guarde `code_verifier` até trocar o code (expira em minutos)
* Use credenciais **DEV** em homologação e **PRODUCTION** só em produção
* Revogue tokens ao desconectar integrações

## vs API Key

|                 | API Key                           | OAuth2                                    |
| --------------- | --------------------------------- | ----------------------------------------- |
| Uso             | Server-to-server da própria conta | Apps de terceiros autorizados             |
| Auth            | `X-API-Key: gp_live_...`          | `Authorization: Bearer gp_oat_live_...`   |
| Permissões      | Por chave no dashboard            | Scopes no consentimento                   |
| Base URL API    | `https://api.goatpay.com.br/v1`   | Mesma                                     |
| Endpoints OAuth | —                                 | Raiz `https://api.goatpay.com.br/oauth/*` |

## MCP

O [MCP Server](/pages/mcp/overview) autentica com **API key** (`gp_live_...`), não com OAuth bearer. Para automação via MCP, use chave de API; OAuth é para apps que redirecionam usuários ao consentimento.

## Referência de endpoints

| Endpoint       | Documentação                                                    |
| -------------- | --------------------------------------------------------------- |
| Discovery      | [Well-known](/api-reference/endpoint/oauth/well-known)          |
| Autorizar      | [GET /oauth/authorize](/api-reference/endpoint/oauth/authorize) |
| Token          | [POST /oauth/token](/api-reference/endpoint/oauth/token)        |
| Revogar        | [POST /oauth/revoke](/api-reference/endpoint/oauth/revoke)      |
| Conta          | [GET /v1/me](/api-reference/endpoint/account/me)                |
| Gestão de apps | [Guia `/v1/oauth-apps`](/api-reference/guides/oauth-apps)       |

## Gestão de aplicações

Use `X-API-Key: gp_live_...` nas rotas `/v1/oauth-apps/*` — mesmo padrão de [webhooks](/api-reference/endpoint/webhooks/list). Permissões: [oauth-apps](/pages/guides/api-permissions#aplicações-oauth).

| Papel                 | API                                                                             | Dashboard                                                                       |
| --------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| **Dono da aplicação** | [Guia oauth-apps](/api-reference/guides/oauth-apps)                             | [Aplicações OAuth](https://app.goatpay.com.br/dashboard/integrations/developer) |
| **Resource owner**    | [authorized-apps/list](/api-reference/endpoint/oauth-apps/authorized-apps-list) | [Conexões](https://app.goatpay.com.br/dashboard/account/connections#apps-oauth) |