OAuth 2.1

O Pingo Notify roda o próprio servidor de autorização OAuth 2.1. É dele que sai a credencial de software que age em nome de uma pessoa — um assistente de IA, uma integração de terceiro, qualquer coisa a que você prefira não entregar um token de API.

Qual credencial usar

Nunca envie os dois headers. Num endpoint que espera um, o outro é ignorado, não somado.

O fluxo

Cinco chamadas. 1 e 2 acontecem uma vez por aplicação, 3 uma vez por pessoa que autoriza, 4 em toda requisição, 5 mais ou menos a cada hora.

1 — Registre o cliente

POST /v3/oauth/register (RFC 7591). Aberto, sem credencial, responde 201.

curl -X POST https://api.pingonotify.com/v3/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Assistente da Acme",
    "redirect_uris": ["https://acme.example/oauth/callback"],
    "token_endpoint_auth_method": "none",
    "grant_types": ["authorization_code", "refresh_token"],
    "scope": "profile connections:read messages:send"
  }'

{
  "client_id": "xf3K9…",
  "client_id_issued_at": 1780000000,
  "client_secret_expires_at": 0,
  "client_name": "Assistente da Acme",
  "redirect_uris": ["https://acme.example/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "profile connections:read messages:send"
}

client_secret só aparece para cliente confidencial, e só nesta resposta.

scope omitido concede ao cliente todos os escopos pedíveis. Registrar não é aprovar: um cliente registrado assim não tem dono nem workspace até que alguém o autorize.

2 — Mande a pessoa para o /authorize

GET /v3/oauth/authorize, no navegador. Não é chamada de API — responde sempre 302.

PKCE é obrigatório para todo cliente, inclusive os confidenciais.

A pessoa entra na conta, escolhe um workspace e aprova. Aí o navegador cai na sua redirect_uri com code, state e iss.

3 — Troque o código

POST /v3/oauth/token, em application/x-www-form-urlencoded ou JSON.

curl -X POST https://api.pingonotify.com/v3/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=aG9sYS4uLg \
  -d redirect_uri=https://acme.example/oauth/callback \
  -d client_id=xf3K9... \
  -d code_verifier=dBjftJeZ4CVP...

{
  "access_token": "eyJ…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "8xLOxBt…",
  "scope": "profile connections:read messages:send"
}

refresh_token só aparece se o cliente registrou esse grant. Cliente público não manda client_secret; confidencial manda, por HTTP Basic ou como campo do formulário.

O código vale 60 segundos e uma vez só. Repetir o seu próprio código revoga a concessão inteira — isso é detecção de reuso, não defeito.

4 — Chame a API

curl https://api.pingonotify.com/v3/connections \
  -H "Authorization: Bearer eyJ…"

Três regras que não têm equivalente do lado do token de API:

• O workspace é fixo. Mandar X-Account-Id de outro workspace responde 403 — This access token is bound to a different workspace; re-authorize to switch.
• Escopo é teto, nunca concessão. A permissão efetiva é a interseção entre os escopos aprovados e o que o papel daquela pessoa permite. Um token com helpdesk:write na mão de um Agent continua fazendo só o que um Agent faz.
• resource prende o token a um caminho. Peça https://api.pingonotify.com/v3/mcp e o token é aceito sob /v3/mcp e responde 401 em todo o resto. Omita resource e o token vale na API inteira. Peça o recurso que você de fato pretende chamar.

Qualquer coisa que nenhum escopo cubra está fechada para token OAuth, e ela diz isso: this operation is not available to OAuth clients. A gestão de consentimento é o caso notável — nenhum escopo a alcança, então uma aplicação nunca consegue listar nem revogar o acesso de outra.

5 — Renove

curl -X POST https://api.pingonotify.com/v3/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=refresh_token \
  -d refresh_token=8xLOxBt... \
  -d client_id=xf3K9...

A resposta tem a mesma forma do passo 3, com um refresh token novo. A rotação é obrigatória: o que você apresentou morre no instante em que o par novo é emitido. Guarde o novo antes de usar o access token novo.

Tanto scope quanto resource só podem estreitar na renovação. Pedir mais devolve invalid_scope ou invalid_target.

Escopos

Doze escopos podem ser pedidos. O legacy existe, mas nenhum cliente pode pedi-lo — ele pertence à ponte do token de API da v1.

Peça o mínimo. Todo escopo a mais é uma linha na tela de consentimento que a pessoa pode recusar — e recusar estreita a aprovação inteira.

Como o seu app aparece na tela

O usuário vê o nome, o logo e o site que você registrou — e um aviso quando o cliente se registrou sozinho pelo endpoint dinâmico, dizendo que o nome exibido foi escolhido pelo próprio app.

Aplicativos que o Pingo verificou exibem um selo Verificado pelo Pingo no lugar desse aviso. A verificação é concedida pela plataforma e confirma quem publica o aplicativo — ela não muda o que ele pode fazer nem pula o consentimento: as permissões continuam sendo escolhidas pelo usuário, uma a uma. Não há como um aplicativo se autodeclarar verificado.

Revogando

O revoke responde 200 para qualquer entrada, inclusive um token que nunca existiu. Isso é de propósito: responder diferente transformaria o endpoint num oráculo para adivinhar token válido.

Reaprovar uma aplicação com menos escopos também revoga os tokens já emitidos sob a aprovação antiga, para que a tela de consentimento e a realidade nunca discordem.

Erros

Onde o erro chega importa mais que o código dele, porque é isso que decide o que o seu cliente tem de parsear. São três lugares.

Como corpo JSON

O corpo é exatamente { "error": "…", "error_description": "…" } — sem outro envelope, sem campo statusCode.

Na sua redirect_uri

Assim que client_id e redirect_uri são validados, todo erro restante do authorize vira um 302 para o seu callback, nunca um corpo JSON — responder no corpo antes desse ponto transformaria o endpoint num open redirect. Parseie a query, não o status:

https://acme.example/oauth/callback?error=invalid_scope&error_description=…&state=…&iss=https://api.pingonotify.com

O iss existe para você saber qual servidor de autorização respondeu (RFC 9207). Os códigos que chegam por aqui: unsupported_response_type, unauthorized_client, invalid_request, invalid_scope, invalid_target, login_required, consent_required, access_denied, server_error.

access_denied significa que uma pessoa recusou, ou que o papel dela não permite autorizar aquele workspace. Não há o que repetir.

Numa chamada de API

Os dois levam um header WWW-Authenticate, e no insufficient_scope ele nomeia o scope que falta:

WWW-Authenticate: Bearer realm="pingo", error="invalid_token",
  error_description="the access token is invalid, expired or revoked",
  resource_metadata="https://api.pingonotify.com/.well-known/oauth-protected-resource/v3/mcp"

Siga o resource_metadata em vez de fixar endpoints no código — ele é o fio de volta ao servidor de autorização.

Validades e limites

Descoberta

Não fixe os endpoints no código. Os dois documentos são públicos, não pedem credencial e são a forma suportada de achar tudo que está acima: