OAuth Apps

Use OAuth Apps to give a third-party app access to your Chargebee site without sharing an API key. That includes apps such as ChartMogul, TaxJar, or a custom analytics tool.

If you share an API key, the partner can keep using it until you replace it. With OAuth Apps, the partner registers with Chargebee and asks for the permissions they need. You review the request and approve or deny it. If you approve, Chargebee gives the partner temporary credentials that work only for your site and those permissions.

Chargebee records which partner made each API call. You can revoke access at any time without changing your API keys.

How OAuth access to Chargebee works

The flow follows the OAuth 2.0 Authorization Code grant:

1. The partner starts the request. The partner redirects you to Chargebee's authorization endpoint, passing their client_id and the scopes they require.
2. You review and consent. Chargebee shows a consent screen with the partner's name and the permissions being requested. You approve or deny.
3. Chargebee issues an authorization code. On approval, Chargebee redirects you to the partner's redirect_uri with a short-lived code.
4. The partner exchanges the code for tokens. The partner's server calls Chargebee's token endpoint and receives an access_token and a refresh_token.
5. The partner calls the Chargebee API. Later API requests use the access_token in the Authorization header instead of an API key.

Chargebee attributes each API call to the partner that made it.

Prerequisites for OAuth Apps

• The Admin or Owner role on the Chargebee site where you register the app.
• For a Chargebee partner listing, a registered partner account. Contact partners@chargebee.com to register.
• A publicly reachable redirect_uri on the partner's server. Chargebee calls this URI after you consent. The URI must use HTTPS. IP addresses are not supported.

Create an OAuth app

1. Go to Settings > Configure Chargebee.

2. Under API Keys and Events, click Oauth Apps.

   

3. Click + Create OAuth App.

4. Enter a Client Name.

5. Select an Application Type. Select Public if you want the application to show up in the marketplace. Select Private for an app that stays off the marketplace.

6. Enter one or more Redirect URIs. Use comma-separated values for multiple URIs. These are the callback URLs Chargebee redirects to after authorization. IP addresses are not supported.

7. Select one or more Roles. Request only the access the integration needs.

   

8. Click Save.

After you save, Chargebee issues a Client ID and Client Secret. Open the app from the OAuth Apps list to copy the Client ID, regenerate the client secret, and upload an Application Logo.

Chargebee rejects authorization requests that use a redirect URI you have not registered on the app.

OAuth app roles

Roles on an OAuth app follow the same access model as API keys. Select only the roles the integration needs. You see the requested permissions on the consent screen.

The create form lists these roles:

• Read Only Access
• Write Access
• Read Transactional Data
• Read Product Configuration
• Growth Read Access
• Full Access
• Update Access
• Growth Write Access

The partner requests the matching scopes when they send you to the authorization endpoint. For example, read_only_access.

Manage OAuth apps

Registered apps appear on the OAuth Apps tab. Each row shows the client name, whether the app is private, and the roles granted.

Click the more options icon on an app, then choose:

• Edit: You can change the client name, application type, redirect URIs, roles, or logo, and copy the Client ID or regenerate the client secret.
• Disable: You can stop the app from being used.
• Delete: You can remove the OAuth app.

Disable and Delete apply to the OAuth app registration. They are not the same as revoking a connected app's access to your site.

Revoke access for a connected app

After you approve a partner, the app appears on the Connected Apps tab. Connected Apps lists each app that currently has access to your site, the access granted, and when the connection was created and last updated.

To end that access, go to Settings > Configure Chargebee > API Keys and Events > Connected Apps, click the more options icon, and click Revoke.

When you revoke access, the active access token is invalidated immediately and the refresh token cannot be used to obtain new tokens. The partner must prompt you to authorize the integration again.

How partners authorize and call the Chargebee API

The following steps are for the partner or developer who implements the integration. You still approve access in Chargebee, manage the OAuth app registration, and revoke connected apps.

Redirect the Chargebee customer to the authorization endpoint

The partner sends you to:

GET https://app.chargebee.com/oauth/authorize

Example:

https://app.chargebee.com/oauth/authorize
  ?client_id=cb_partner_abc123
  &redirect_uri=https://app.yourpartner.com/chargebee/callback
  &response_type=code
  &scope=read_only_access
  &state=xK9mP2q7

Handle the callback

After you consent, Chargebee redirects to the partner's redirect_uri:

GET https://app.yourpartner.com/chargebee/callback
  ?code=AUTH_CODE
  &state=xK9mP2q7
  &site=acme-test

The partner must validate the state parameter before continuing. If it does not match the value sent to the authorization endpoint, the partner must discard the request.

If you deny the request, Chargebee redirects with error=access_denied instead of a code.

Exchange the code for tokens

The partner makes a server-side POST request to the token endpoint. This call must not run from client-side code.

POST https://app.chargebee.com/oauth/token

Example:

curl -X POST https://app.chargebee.com/oauth/token \
  -u cb_partner_abc123:your_client_secret \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=https://app.yourpartner.com/chargebee/callback"

Response:

{
  "access_token": "cbat_eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "cbrt_eyJhbGciOi...",
  "scope": "read_only_access",
  "site": "acme-test"
}

The partner must store the refresh_token securely. It is required to obtain new access tokens after expiry.

Call the Chargebee API with the access token

The partner passes the access_token as a Bearer token:

curl https://acme-test.chargebee.com/api/v2/subscriptions \
  -H "Authorization: Bearer cbat_eyJhbGciOi..."

All requests are scoped to the site returned in the token response. Requests that exceed the granted scopes return 403 Forbidden.

Refresh the access token

Access tokens expire after 3600 seconds (1 hour). The partner uses the refresh_token to get a new access token without asking you to authorize again:

curl -X POST https://app.chargebee.com/oauth/token \
  -u cb_partner_abc123:your_client_secret \
  -d "grant_type=refresh_token" \
  -d "refresh_token=cbrt_eyJhbGciOi..."

The response contains a new access_token and a new refresh_token. The partner must replace both stored values. Refresh tokens are rotated on every use.

If you revoked access, the token endpoint returns 400 invalid_grant. The partner should prompt you to authorize the integration again rather than retrying the refresh indefinitely.

OAuth error reference

Security practices for OAuth apps

• Keep the client_secret on the server. Never expose it in client-side code, mobile apps, or public repositories.
• Always validate state. Generate a cryptographically random value per authorization attempt and verify it on callback return.
• Store access_token and refresh_token with the same care as passwords. Use encrypted storage and restrict access to the services that need them.
• Request only the roles and scopes the integration uses.
• Handle invalid_grant without retrying refresh-token exchanges indefinitely. Prompt the Chargebee customer to authorize again.
• Use HTTPS for Chargebee endpoints and for every redirect_uri.