The flow
The authorization server ishttps://auth.dodopayments.com. Your app uses the authorization code flow with PKCE (S256) and the client secret.
The merchant must be an owner or an admin of the business. The merchant approves all scopes or none.
Choose the mode
Setresource in each authorization request to the API host of the mode:
A request with no
resource fails with invalid_target. The API calls for an install go to the same host. The examples on this page use the test host.
Step 1: Send the merchant to the authorize URL
Create a randomcode_verifier. Compute code_challenge as the Base64URL SHA-256 hash of the verifier. Store the verifier and a random state for the callback.
client_id is the app ID. The merchant sees the consent screen with your reasons for each scope.
Step 2: Receive the code
Dodo Payments redirects to yourredirect_uri with code and state. Check that state matches the stored value. The redirect URI must be one of the approved redirect URIs, with an exact match.
Step 3: Exchange the code for tokens
Send the client ID and the client secret with HTTP Basic authentication.access_token, refresh_token, expires_in, and scope. Store the tokens with the installation of the merchant. The installation_id arrives in the app.installed webhook.
Activation is asynchronous. Your app can receive the code and call the API before the installation is
active and before the app.installed webhook arrives. Do not wait for the webhook to exchange the code.Step 4: Call the API
403. For example, a token with the scope payments:read gets 403 on a route of a different scope.
Scopes for each installation
The scopes are set for each installation. If you add a scope to the app later, existing installs keep their old scopes. The merchant sees a banner and must approve the new scopes. Calls that need a new scope fail until the merchant approves. If you remove a scope from a live app, the scopes of the current installs are reduced too. Dodo Payments adds theapp_settings:read scope to the tokens of your app automatically. See Read settings.
Refresh tokens
app.uninstalled.
Revocation and uninstall
- A merchant owner or admin can uninstall your app at any time. The install stays active if the person who installed it leaves the business.
- Revocation takes effect within 2 minutes. During that time a revoked token can still work. After that time the API returns
401. - You can revoke a token at
https://auth.dodopayments.com/oauth2/revoke. - If you rotate the client secret, the old secret stops working at once.
- If a reviewer suspends your app, introspection and the token endpoint refuse its tokens, and its webhooks stop.
Rate limits
Each pair of app and business is limited to 20 requests each second and 120 requests each minute. A call over the limit returns429. Retry with a back-off.