Skip to main content

The flow

The authorization server is https://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

Set resource 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 random code_verifier. Compute code_challenge as the Base64URL SHA-256 hash of the verifier. Store the verifier and a random state for the callback.
The 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 your redirect_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.
The response holds 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

A token is for one installation. It works only for that business, in that mode, and only for the granted scopes. A call that needs a scope that the install does not have returns 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 the app_settings:read scope to the tokens of your app automatically. See Read settings.

Refresh tokens

Store the new refresh token and discard the old one. If you use an old refresh token a second time, Dodo Payments revokes the grant, and the install gets app.uninstalled.
Refresh one token at a time for each installation. Two parallel refreshes with the same refresh token can revoke the grant.

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 returns 429. Retry with a back-off.

Common errors

Last modified on November 16, 2026