Registering an OAuth app

An OAuth application is the developer-side record (client_id, redirect URIs, requested scopes) that lets you run the Authorization Code with PKCE flow against a merchant’s SouthPay account. Tokens issued through it look like spo_… and reach any public endpoint the granted scopes allow. Register the app once, then implement the runtime flow described in Authentication.

Managing apps is a developer-portal task, not a runtime API. /api/v2/merchants/oauth_apps accepts a logged-in dashboard session only. An sp_ API key or an spo_ token gets 401. Create and edit apps at app.southpay.io; the request shapes below describe what the dashboard does on your behalf.

Public or confidential

	Public	Confidential
`confidential`	`false`	`true`
Client secret	None	Issued once at creation
For	Browser, mobile and desktop clients	Server-side clients that can keep a secret
Token endpoint auth	PKCE only	PKCE plus `client_secret_basic` or `client_secret_post`

PKCE with S256 is mandatory for both kinds. A confidential client secret does not exempt you from sending code_challenge, and plain is not accepted. A request without a challenge fails with invalid_request.

confidential is immutable after creation, as is client_id. To change either, register a new app.

Scopes

An app declares the scopes it may ever request. Eighteen exist; the merchant approves a subset at consent time.

Scope	Grants
`profile`	The merchant’s name and email, via `GET /oauth/userinfo`
`stores:read`	Read the merchant’s store record
`payments:read`	List and read payment intents, events and reconciliation
`payments:write`	Create payment intents
`refunds:read`	List and read refunds
`refunds:write`	Issue refunds
`payouts:read`	List and read payouts and payout schedules
`payouts:write`	Create, retry and quote payouts; manage schedules
`balances:read`	Read balances and reports
`billing:read`	Read customers, invoices, products, prices and subscriptions
`billing:write`	Manage all of the above
`webhooks:read`	Read webhook endpoints and deliveries
`webhooks:write`	Create, update, rotate and delete webhook endpoints
`accounts:read`	Read a platform’s sub-merchants
`accounts:write`	Create and update sub-merchants, verification, onboarding links
`accounts:act`	Send `X-Southpay-Account` to act as a sub-merchant
`agents:write`	Exchange the token for an `spa_` agent credential
`offline_access`	Issue a refresh token alongside the access token

offline_access changes the access token lifetime, and not in the direction people expect. With it, the access token lives one hour and you must refresh. Without it, the access token lives 90 days and there is no refresh token. Decide which model your app wants before you register it. See Token lifetimes.

One rough edge in the consent flow to work around:

The consent screen renders no description for accounts:read, accounts:write, accounts:act and agents:write. Merchants see the scope name and nothing else. If your app requests any of them, explain what they do in your own UI before you send the merchant to the authorize page.

Creating an app

POST /api/v2/merchants/oauth_apps
Authorization: Bearer <DASHBOARD_JWT>
Content-Type: application/json

{
  "oauth_application": {
    "name": "Acme Commerce Plugin",
    "website_url": "https://acme.example",
    "logo_url": "https://acme.example/logo.png",
    "confidential": true,
    "redirect_uris": ["https://acme.example/oauth/callback"],
    "scopes": ["payments:write", "webhooks:write", "offline_access"]
  }
}

{
  "id": "4e1b8c73-0a25-4f96-b8d0-71c3ea5f2649",
  "name": "Acme Commerce Plugin",
  "client_id": "spo_app_dev_9f4c1a7e30bd52c684f10a3b",
  "client_secret": "spcs_XnQ2r7Yv...",
  "website_url": "https://acme.example",
  "logo_url": "https://acme.example/logo.png",
  "redirect_uris": ["https://acme.example/oauth/callback"],
  "scopes": ["payments:write", "webhooks:write", "offline_access"],
  "confidential": true,
  "active": true,
  "has_secret": true,
  "created_at": "2026-08-07T12:00:00.000Z"
}

client_secret is returned only here and from rotate_secret. Its prefix is spcs_. Every later read omits the field entirely and tells you only has_secret: true.

Field	Required	Notes
`name`	Yes	Shown to the merchant on the consent screen
`confidential`	Yes	Immutable. `true` issues a secret.
`redirect_uris`	Yes	Exact-match allowlist. The `redirect_uri` on the authorize call must appear here verbatim.
`scopes`	Yes	Subset of the eighteen above
`website_url`	No	Public marketing URL
`logo_url`	No	Shown on the consent screen

id is a bare UUID. client_id is spo_app_dev_ followed by 24 hex characters. Validation failures come back as {"errors": ["…"]} with 422, the list shape rather than the object shape. See Errors.

Reading and updating

GET /api/v2/merchants/oauth_apps returns a bare array of your apps, newest first. GET /api/v2/merchants/oauth_apps/{id} returns one. PATCH accepts name, website_url, logo_url, active, redirect_uris and scopes. It does not accept client_id or confidential. Narrowing scopes does not retroactively narrow tokens already issued. Existing grants keep whatever the merchant approved until they expire or are revoked.

Rotating the secret

POST /api/v2/merchants/oauth_apps/{id}/rotate_secret
Authorization: Bearer <DASHBOARD_JWT>

Returns the app with a fresh client_secret. Public apps get 422 {"error": "not_confidential", "error_description": "Only confidential apps have secrets"}.

Rotation invalidates the old secret immediately, with no overlap window. Every server using it starts failing client authentication at the token endpoint the moment the request returns. Deploy the new value first, or accept a gap.

Deleting

DELETE /api/v2/merchants/oauth_apps/{id}

Returns 204 and sets active: false. It is a deactivation, not a hard delete. Access tokens already issued keep working until they expire; refresh attempts against a deactivated app fail.

Discovery

https://api.southpay.io/.well-known/oauth-authorization-server advertises the authorize, token, revoke and userinfo endpoints, plus:

Field	Value
`response_types_supported`	`["code"]`
`grant_types_supported`	`["authorization_code", "refresh_token"]`
`code_challenge_methods_supported`	`["S256"]`
`token_endpoint_auth_methods_supported`	`["none", "client_secret_basic", "client_secret_post"]`

Use it for dynamic configuration rather than hardcoding paths.

Getting started

Authentication

Core resources

Recurring

Checkout

Agentic commerce

Platform

Integrations

Building reliably

Changelog

Registering an OAuth app

Public or confidential

Scopes

Creating an app

Reading and updating

Rotating the secret

Deleting

Discovery

​Public or confidential

​Scopes

​Creating an app

​Reading and updating

​Rotating the secret

​Deleting

​Discovery

Public or confidential

Scopes

Creating an app

Reading and updating

Rotating the secret

Deleting

Discovery