OAuth and scopes

Apps connect to a merchant's account with OAuth 2.0 and PKCE. The merchant sees what you ask for in plain words and chooses Allow; you get a token for that merchant.

1Register the app

Create the app under Apps in the portal with its redirect URLs and the scopes it needs. You get a client ID (inkid_…) and a client secret. Inkress reviews an app before merchants outside your organisation can connect it.

2Send the merchant to approve

Redirect to https://inkress.com/oauth/authorize with response_type=code, client_id, redirect_uri, scope (space separated), state, and a PKCE code_challenge with code_challenge_method=S256. On the test environment the page is https://dev.inkress.com/oauth/authorize.

3Swap the code for a token

Inkress sends the merchant back to your redirect_uri with code and state. From your server, post to /api/v1/hooks/oauth/token with grant_type=authorization_code, the code, your client ID and secret, the redirect_uri and the code_verifier.

Access tokens start with inka_ and last an hour (expires_in 3600). Ask for offline_access to get a refresh token, and swap it with grant_type=refresh_token.

Scopes

Scope	What it allows
`orders:read`	List and view orders, their lines and details.
`orders:write`	Create and update orders.
`orders:refund`	Refund a card payment, in full or in part.
`customers:read`	View customers and their addresses. Personal data.
`customers:write`	Create and update customers and addresses.
`products:read`	View products, variants, categories and tags.
`products:write`	Create and update products, variants, categories and tags.
`payment_links:read`	View payment links.
`payment_links:write`	Create and update payment links, including turning one off.
`payments:read`	View captured transactions.
`payouts:read`	View payouts.
`payouts:create`	Ask for a payout. Inkress approves it.
`wallet:read`	View the wallet balance.
`financial_accounts:read`	View the merchant's bank and wallet accounts.
`reputation:read`	Read account standing and verification status.
`kyc:write`	Submit verification documents.
`merchant_limits:request`	Ask for a temporary limit increase.
`billing:write`	Manage billing plans and view subscriptions. Lets the app bill customers on a schedule.
`cards:charge`	Charge a saved card on demand.
`webhooks:manage`	Add, change and remove webhook endpoints.
`merchant_profile:read`	Read the business name, currency and details.
`merchant_profile:write`	Update the business profile.
`user:email`	The approving person's email and name, with the code exchange only.
`offline_access`	A refresh token alongside the access token.

Calls outside what the merchant approved return 401. Merchants can disconnect your app at any time; its tokens stop working.

The discovery document at /.well-known/oauth-authorization-server on each API host lists the endpoints and every scope.

PreviousPayouts NextEmbedded apps

Was this page helpful?Updated Oct 8, 2026