Creating a Custom OAuth Application

CData embeds OAuth Application Credentials with CData branding that can be used when connecting to Stripe via a desktop application or a headless machine.

However, you must create a custom OAuth application to connect to Stripe via the Web. And since custom OAuth applications seamlessly support all three commonly-used auth flows, you might want to create custom OAuth applications (use your own OAuth Application Credentials) for those auth flows anyway.

Custom OAuth applications are useful if you want to:

• control branding of the authentication dialog;
• control the redirect URI that the application redirects the user to after the user authenticates; or
• customize the permissions that you are requesting from the user.

Procedure

Creating a custom OAuth application entails:

• creating a custom application,
• creating an OAuth installation link,
• publishing the application to the Stripe App Marketplace,
• installing and authorizing the application, and
• exchanging your OAuth authorization code for an access token.

Note: All of the following instructions are performed via the Stripe Command Line Interface (CLI).

Create the Application

1. In the Stripe CLI, enter:
   

   stripe apps create <application_name>

   Stripe creates stripe-app.json, a manifest file for the new application.
2. Edit the application manifest file:
   • Set stripe_api_access_type to oauth.
   • Set disribution_type to public.
   • Configure your allowed_redirect_uris to indicate the URLs to which users are redirected after installing your custom OAuth application. The first one in the list is used as the default redirect.
   • Add all the permissions your custom application requires.

     Your application manifest should now look similar to this:
     

     {
     	"id": "com.example.my-application",
     	"version": "0.0,1",
     	"name": "Your Stripe Application",
     	"icon": "./[YOUR_APPLICATION]_icon_32.png",
     	"permissions": [
     		// Your application permissions here
     	],
     	"stripe_api_access_type": "oauth",
     	"distribution_type": "public",
     	"allowed_redirect_uris": [
     		// Your redirect uris here
     	]
     }

3. If desired, add UI exensions to your application. You may want to add a settings view to enable your users to configure settings, or to link to your application's documentation.
4. To upload your application to Stripe, enter:
   

   stripe apps upload

5. To test your new custom application:
   • Navigate to your application's details page.
   • Open the External test tab.
   • Click Get started. This initiates an external test.
   • Navigate to the Test OAuth section and acess the authorize links. Use these links to test your application against different accounts.

Create the OAuth Install Link

From your web page, redirect to your OAuth install link with these parameters:

https://marketplace.stripe.com/oauth/v2/authorize?
client_id=${clientId}&redirect_url=${redirectUrl}&state=$(state).

Note: To prevent CSRF attacks, add the recommended state parameter and pass along a unique token as the value. For further information, see https://docs.stripe.com/stripe-apps/api-authentication/oauth#url-parameters.

Publish the Application

When you are ready to publish your custom OAuth application to the Stripe App Marketplace, submit it for review.

When you submit the application for review, you must 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.

(OAuth install links do not work until the application is published, but the Marketplace staff can use the link you provide to install and test your application.)

Install and Authorize the Application

1. In your browser, open your OAuth install link. If necessary, adjust the query parameters to change the redirect URL to one that your custom application supports.
2. View and accept the permissions to install the application.

The application installation process begins. When installation is complete, the user is either redirected to the first callback URL you defined in the app manifest, or to a specific URL parameter.

Exchange the Authorization Code for an Access Token

Your callback URL receives an OAuth authorization code parameter that is only valid for five minutes, and can only be used once. The backend of your custom application exchanges this code for an API access token and the refresh token.

Your backend code implements the exchange via an OAuth client library, using this command:

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

If the command is successful, Stripe displays a response similar to the following:

{
  "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 the Access Token

Access tokens expire in one hour, and refresh tokens expire after one 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 first 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.

To exchange the access token for a refresh token, enter the following curl command:

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

If the command is successful, you receive a response similar to:

{
  "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"
}

Once you obtain a new refresh token, the previous refresh token expires. Store the new refresh token securely in your backend, and use the refresh token to obtain a new access token any time you must access the Stripe API on behalf of the Stripe user.

To validate the access token, enter a request to the Stripe API, similar to:

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