OAuth App (multi‑merchant)

The process uses a client_credentials OAuth flow scoped by a unique instanceId for each merchant who installs your app.

Steps:

1. App Credentials SetupDecide your redirectUrl - The URL where Rise will redirect merchants after they approve the installation. It must be HTTPS, and you should set Cross-Origin-Opener-Policy (COOP) to unsafe-none on this endpoint.

2. Merchant Installation FlowThis is the multi-step “dance” that happens when a new merchant installs your app. Start by referring the installer (the merchant) to:

https://platform.rise.ai/protected/app-installer/install?appId=<APP_ID>&redirectUrl=<ENCODED_REDIRECT_URL>

After the merchant approves, Rise redirects to your redirectUrl with code and instanceId query parameters.Save the instanceId — you'll use it along with your app credentials to generate access tokens for this merchant.Authenticate the user at your redirectUrl so you know which merchant account to associate with the instanceId.

3. Create Access TokenExchange your app credentials and the merchant's instanceId for an access token:

curl -X POST 'https://platform.rise.ai/oauth2/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "<APP_ID>",
    "client_secret": "<APP_SECRET>",
    "instance_id": "<INSTANCE_ID>"
  }'

Store the access_token (valid for ~4 hours). Refresh it before expiration for each merchant instanceId.

Using SDKRecommended for automatic token refresh and simplified OAuth flowWe provide official SDKs in several languages (TypeScript, Java, Python, .NET) with built-in OAuth support, automatic token refresh, and type-safe API access.View our SDK documentation for OAuth setup instructions and code examples.

Using REST APIFor direct API access, send requests with the following required headers:

• Authorization: Bearer <ACCESS_TOKEN>• Content-Type: application/json

Example: Query wallets

curl -X POST \
  'https://platform.rise.ai/v1/rise/wallets/query' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  --data-binary '{}'

You're done. Build your flows using the relevant Rise service endpoints. Repeat token creation for each merchant instanceId that installs your app.

💡 Want to see this in action? Check out our OAuth Demo project for a complete working example.