OAuth 2.1

Pingo Notify runs its own OAuth 2.1 authorization server. It issues the credential for software that acts on behalf of a person — an AI assistant, a third-party integration, anything you would rather not hand an API key to.

Which credential to use

Never send both headers. On an endpoint that expects one, the other is ignored, not merged.

The flow

Five calls. 1 and 2 happen once per application, 3 once per person who authorizes, 4 on every request, 5 about once an hour.

1 — Register the client

POST /v3/oauth/register (RFC 7591). Open, no credential needed, answers 201.

curl -X POST https://api.pingonotify.com/v3/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Acme Assistant",
    "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": "Acme Assistant",
  "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 is present only for a confidential client, and only in this response.

scope omitted grants the client every requestable scope. Registering is not approving: a client registered this way has no owner and no workspace until a person authorizes it.

2 — Send the person to /authorize

GET /v3/oauth/authorize, in a browser. Not an API call — it always answers 302.

PKCE is mandatory for every client, confidential ones included.

The person signs in, picks a workspace and approves. Then the browser lands on your redirect_uri with code, state and iss.

3 — Exchange the code

POST /v3/oauth/token, application/x-www-form-urlencoded or 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 appears only if the client registered that grant. A public client must not send client_secret; a confidential one must, by HTTP Basic or as a form field.

The code is valid for 60 seconds and once. Replaying your own code revokes the whole grant — that is reuse detection, not a bug.

4 — Call the API

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

Three rules that have no equivalent on the API-key side:

• The workspace is fixed. Sending X-Account-Id for a different workspace answers 403 — This access token is bound to a different workspace; re-authorize to switch.
• The scope is a ceiling, never a grant. Effective permission is the intersection of the approved scopes and what that person's role allows. A token holding helpdesk:write in the hands of an Agent still does only what an Agent does.
• resource binds the token to a path. Ask for https://api.pingonotify.com/v3/mcp and the token is accepted under /v3/mcp and answers 401 everywhere else. Omit resource and the token works across the API. Ask for the resource you actually intend to call.

Anything with no scope that covers it is closed to OAuth tokens entirely, and says so: this operation is not available to OAuth clients. Consent management is the notable case — no scope reaches it, so an app can never list or revoke another app's access.

5 — Refresh

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

The response has the same shape as step 3, with a new refresh token. Rotation is mandatory: the one you presented is dead the moment the new pair is issued. Store the new one before you use the new access token.

Both scope and resource may only narrow on refresh. Asking for more returns invalid_scope or invalid_target.

Scopes

Twelve scopes can be requested. legacy exists but no client may ask for it — it belongs to the v1 API-key bridge.

Ask for the least you need. Every extra scope is a line on the consent screen that a person can refuse, and refusing narrows the whole approval.

How your app shows up on the screen

The user sees the name, logo and website you registered — plus a warning when the client registered itself through the dynamic endpoint, saying the displayed name was chosen by the app itself.

Applications Pingo has verified show a Verified by Pingo badge in place of that warning. Verification is granted by the platform and confirms who publishes the application — it does not change what the app can do and does not skip consent: permissions are still the user's choice, one by one. There is no way for an application to mark itself as verified.

Revoking

revoke answers 200 for any input, including a token that never existed. That is deliberate: a different answer would turn the endpoint into an oracle for guessing valid tokens.

Re-approving an app with fewer scopes also revokes the tokens already issued under the old approval, so the consent screen and reality never disagree.

Errors

Where an error arrives matters more than its code, because it decides what your client has to parse. There are three places.

As a JSON body

The body is exactly { "error": "…", "error_description": "…" } — no other envelope, no statusCode field.

On your redirect_uri

Once client_id and redirect_uri check out, every remaining authorize error becomes a 302 to your callback, never a JSON body — answering in the body before that point would make the endpoint an open redirect. Parse the query, not the status:

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

iss is there so you can tell which authorization server answered (RFC 9207). The codes that arrive this way: unsupported_response_type, unauthorized_client, invalid_request, invalid_scope, invalid_target, login_required, consent_required, access_denied, server_error.

access_denied means a person refused, or their role does not allow authorizing that workspace. There is nothing to retry.

On an API call

Both carry a WWW-Authenticate header, and on insufficient_scope it names the missing scope:

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"

Follow resource_metadata instead of hardcoding endpoints — it is the thread back to the authorization server.

Lifetimes and limits

Discovery

Do not hardcode the endpoints. Both documents are public, need no credential, and are the supported way to find everything above: