Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Overview
Versioning
Changelog
Upgrade your API version
Upgrade your SDK version
Developer tools
SDKs
API
Testing
Workbench
Event Destinations
Workflows
Stripe CLI
Stripe Shell
Developers Dashboard
Agent toolkit
Stripe health alertsBuilding with LLMsStripe for Visual Studio CodeFile uploads
Security
Security
Extend Stripe
Stripe Apps
    Overview
    Get started
    Create an app
    How Stripe Apps work
    Sample apps
    Build an app
    Store secrets
    API authentication methods
      OAuth 2.0
      Restricted API key
    Authorization flows
    Server-side logic
    Listen to events
    Handle different modes
    Enable sandbox support
    App settings page
    Build a UI
    Onboarding
    Distribute your app
    Distribution options
    Upload your app
    Versions and releases
    Test your app
    Publish your app
    Promote your app
    Add deep links
    Create install links
    Assign roles in UI extensions
    Post-install actions
    App analytics
    Embedded components for Apps
    Embed third-party Stripe Apps
    Migrating to Stripe Apps
    Migrate or build an extension
    Migrate a plugin to Stripe Apps or Stripe Connect
    Reference
    App manifest
    CLI
    Extension SDK
    Permissions
    Viewports
    Design patterns
    Components
Stripe Connectors
Partners
Partner ecosystem
Partner certification
HomeDeveloper toolsStripe AppsAPI authentication methods

OAuth 2.0

Use the industry standard OAuth 2.0 to authenticate requests to the Stripe API on behalf of your users.

Copy page

A user authenticating with OAuth follows these steps.

  1. On your site, the user clicks a link that redirects them to Stripe.
  2. On Stripe, the user selects the appropriate account and accepts permissions for installing the app.
  3. After the app is installed, authentication is complete and the user is redirected to a defined URI.
Installing an app with OAuth

Develop your app

  1. Create your Stripe App by running stripe apps create <app-name> in the CLI.

  2. Edit the following fields in the app manifest:

    • Set stripe_api_access_type to oauth.
    • Set distribution_type to public.
    • Set your allowed_redirect_uris. These are the URLs that users are redirected to after installing your app using OAuth. The first one in the list is used as the default redirect.

    Your app manifest should look like this:

    stripe-app.json
    { "id": "com.example.my-app", "version": "0.0.1", "name": "Your Stripe App", "icon": "./[YOUR_APP]_icon_32.png", "permissions": [ // Your app permissions here ], "stripe_api_access_type": "oauth", "distribution_type": "public", "allowed_redirect_uris": [ // Your redirect URIs here ] }
  3. Add all the permissions that your app requires.

  4. (Optional) Add UI extensions to your app. We recommend adding a settings view to allow your users to configure settings or to link to your app’s documentation.

  5. Upload your app to Stripe.

    Command Line
    stripe apps upload

Test your app

  1. Navigate to your app’s details page.
  2. Open the External test tab and click Get started to set up an external test.
  3. Access the authorize links in the Test OAuth section. You can use this link to test with different accounts.

Create your OAuth install link

From your webpage, redirect to your OAuth install link with the following parameters: https://marketplace.stripe.com/oauth/v2/authorize?client_id=${clientId}&redirect_uri=${redirectUrl}&state=${state}.

Stripe generates separate links for both live and test modes. You can find the links in the External test tab.

The location of test OAuth links within the Stripe Dashboard

Security tip

To prevent CSRF attacks, add the recommended state parameter and pass along a unique token as the value. We include the state you provide when redirecting users to your site. Your site can confirm that the state parameter hasn’t been modified. See URL parameters for more information.

Publish your app

Submit your app for review when you are ready to publish it to the Stripe App Marketplace

When submitting an OAuth app for review, you need to provide the Marketplace install URL. This URL must link to a page that can initiate the onboarding and installation process with clear instructions using OAuth install links from the previous step.

Make sure the install URL provided to App Review uses the public OAuth links available within the “Settings” tab.

The location of public OAuth links within the Stripe Dashboard

Note

The public OAuth install links don’t work until the app is published. However, our app review team can install and test your app through this link.

Install your app and authorize

  1. In your browser, open your OAuth install link. You can adjust the query parameters to change the redirect URL to one supported by the app.
  2. View and accept the permissions to install the app. When the installation is complete, the user is redirected to the first callback URL you’ve defined in the app manifest, unless you’ve specified a URL parameter.

Exchange the authorization code for an access token

Your callback URL receives an OAuth authorization code parameter that your backend needs to exchange for an API access token and the refresh token. This authorization code is one-time use only and valid only for 5 minutes, in which your backend needs to exchange the code for the access token. Below is the command that your backend code needs to implement using an OAuth client library.

Command Line
curl -X POST https://api.stripe.com/v1/oauth/token \ -u sk_live_***: \ -d code=ac_*** \ -d grant_type=authorization_code

Note

You’ll need to use the app developer API Key for the relevant mode. To enable this, pass the relevant mode within the state.

Here’s an example response for the above curl command.

{ "access_token": "{{ ACCESS_TOKEN }}", "livemode": true, "refresh_token": "{{ REFRESH_TOKEN }}", "scope": "stripe_apps", "stripe_publishable_key": "pk_live_***", "stripe_user_id": "acct_***", "token_type": "bearer" }

Refresh your access token

Access tokens expire in 1 hour, and refresh tokens expire after 1 year. Refresh tokens are also rolled on every exchange, so the expiration time for the new refresh tokens is always a year from the date that it was generated or rolled. If you exchange a refresh token for an access token within one year, you should never hit the refresh token expiration date.

Here is the equivalent curl command to exchange the access token for a refresh token using your secret key:

Command Line
curl -X POST https://api.stripe.com/v1/oauth/token \ -u sk_live_***: \ -d refresh_token={{ REFRESH_TOKEN }} \ -d grant_type=refresh_token

Here’s an example response.

{ "access_token": "{{ ACCESS_TOKEN }}", "livemode": true, "refresh_token": "{{ REFRESH_TOKEN }}", "scope": "stripe_apps", "stripe_publishable_key": "pk_live_***", "stripe_user_id": "acct_***", "token_type": "bearer" }

You’ll get a new refresh token and the previous refresh token expires. You must securely store the refresh token in your backend and use the refresh token to obtain a fresh access token anytime you want to access the Stripe API on behalf of the Stripe User.

Common mistake

When you refresh the access token you may see an error that says you do not have the required permissions. If you see this, confirm that you’re using the secret key for your account to authorize the API call and that you’re not accidentally using a refresh token, access token, or a restricted key.

You can verify the access token by making a request to the Stripe API. For example:

Command Line
curl https://api.stripe.com/v1/customers \ -u "{{ ACCESS_TOKEN }}"

OptionalCustomize links with URL parameters

Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc