OAuth 2.0

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: a chave é server-to-server da própria conta; OAuth é consentimento do titular da conta.

OAuth2 puro — sem OpenID Connect. Identidade da conta: GET /v1/me com scope account:read. Não há /oauth/userinfo.

Pré-requisitos

Conta merchant com API pública habilitada (solicite ao suporte GoatPay se necessário).
Aplicação registrada via API /v1/oauth-apps ou em Integrações → Aplicações OAuth no dashboard.
Credenciais DEV e PRODUCTION separadas (client_id + client_secret por ambiente).
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 para obter authorization_endpoint, token_endpoint, revocation_endpoint e scopes_supported.

Fluxo completo

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/*

1. Criar aplicação

POST /oauth-apps/create ou dashboard → Aplicações OAuth → nome, descrição e scopes. Gere credenciais DEV e Production; o client_secret aparece uma vez.

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).

3. PKCE

Gere code_verifier e code_challenge (S256). Guarde o verifier no servidor; envie apenas o challenge no authorize.

4. Autorizar

Redirecione para GET /oauth/authorize.

5. Token

Valide state no callback e troque o code em POST /oauth/token.

6. API

Use Authorization: Bearer gp_oat_live_... nas rotas /v1/* dentro dos scopes aprovados.

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`

import { createHash, randomBytes } from "crypto";

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

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

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 para o mapa completo.

Identidade da conta

curl https://api.goatpay.com.br/v1/me \
  -H "Authorization: Bearer gp_oat_live_..."

Documentação: GET /v1/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.

Renovar e revogar

Refresh: grant_type=refresh_token em POST /oauth/token — o refresh anterior é invalidado (rotação).
Revogar: POST /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.

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 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
Autorizar	GET /oauth/authorize
Token	POST /oauth/token
Revogar	POST /oauth/revoke
Conta	GET /v1/me
Gestão de apps	Guia `/v1/oauth-apps`

Gestão de aplicações

Use X-API-Key: gp_live_... nas rotas /v1/oauth-apps/* — mesmo padrão de webhooks. Permissões: oauth-apps.

Papel	API	Dashboard
Dono da aplicação	Guia oauth-apps	Aplicações OAuth
Resource owner	authorized-apps/list	Conexões

Introdução

Webhooks

WebSocket

PIX

Conta

Loja

Subcontas

OAuth 2.0

Pré-requisitos

Descoberta automática

Fluxo completo

Consentimento

PKCE (obrigatório)

Cadeia de scopes

Limites do OAuth vs API key

Identidade da conta

Webhooks

Renovar e revogar

Erros comuns

No redirect (`/oauth/authorize`)

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

Boas práticas

vs API Key

MCP

Referência de endpoints

Gestão de aplicações

​Pré-requisitos

​Descoberta automática

​Fluxo completo

​Consentimento

​PKCE (obrigatório)

​Cadeia de scopes

​Limites do OAuth vs API key

​Identidade da conta

​Webhooks

​Renovar e revogar

​Erros comuns

​No redirect (/oauth/authorize)

​Na API (/v1/* com bearer)

​Boas práticas

​vs API Key

​MCP

​Referência de endpoints

​Gestão de aplicações

Pré-requisitos

Descoberta automática

Fluxo completo

Consentimento

PKCE (obrigatório)

Cadeia de scopes

Limites do OAuth vs API key

Identidade da conta

Webhooks

Renovar e revogar

Erros comuns

No redirect (`/oauth/authorize`)

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

Boas práticas

vs API Key

MCP

Referência de endpoints

Gestão de aplicações