# Back-end app example

Build a Stripe app that performs back-end processing with no user interface.

This guide shows you how to build a back-end Stripe app. It doesn’t provide any user interface other than the default app settings page.

Select the [authentication type](https://docs.stripe.com/stripe-apps/api-authentication.md) that you want to use. If you want to build [a private app](https://docs.stripe.com/stripe-apps/distribution-options.md#share-with-team-members), you can’t use OAuth authentication.

# Platform key

> This is a Platform key for when app-auth-type is platform. View the full page at https://docs.stripe.com/stripe-apps/back-end-app-example?app-auth-type=platform.

The following example shows how to build a Stripe app that uses platform key authentication.

## Create a Stripe account

Before integrating with Stripe, you must create a Stripe account.

1. [Create an account](https://dashboard.stripe.com/register) by entering your email address, full name, country, and creating a password.
1. Fill out your business profile.
1. In the Dashboard, click **Verify your email**. Stripe sends a verification email to your email address.
1. Verify your email address.

> You can continue building your app in a sandbox as you follow the steps in this guide. You need a live Stripe account to publish your app.

## Install Stripe CLI and Apps CLI Plugin

#### javascript

```jsx
# Install Homebrew to run this command: https://brew.sh/
brew install stripe/stripe-cli/stripe
```

#### javascript

```jsx
# Connect the CLI to your dashboard
stripe login
```

#### javascript

```jsx
# Install Apps CLI Plugin
stripe plugin install apps
```

See the [additional instructions](https://docs.stripe.com/stripe-apps/create-app.md) to verify that you’re using CLI v1.12.4 and that node.js is up to date.

## Create your app

#### javascript

```jsx
stripe apps create {my-app-name}
```

After you run this command, it prompts you for the following:

- An app ID, which must be globally unique and can change
- An app display name, which doesn’t need to be unique and that you can change

## Configure your app

In your new directory, find the [stripe-app.json app manifest file](https://docs.stripe.com/stripe-apps/reference/app-manifest.md), and update it as follows:

#### javascript

```jsx
{
   "id": "com.example.example-app", // unique app ID
   "version": "0.0.1",  	 // app version
   "name": "Example App",  // app display name
   "icon": "./[YOUR_APP]_icon_32.png",	// app icon; put the file in the same directory for ease of distribution
   "stripe_api_access_type": "platform",
   "allowed_redirect_uris": ["https://example.com/installed/callback"], // optional redirect URLs
   "distribution_type": "public", // for a private app, set to "private"
   "sandbox_install_compatible": "true",
   "permissions": []
}
```

### Configure installation redirect URLs (optional)

In the `allowed_redirect_uris` array, add the URLs to return your app users to after they install your app from an [install link](https://docs.stripe.com/stripe-apps/install-links.md). The first entry becomes the default. If you don’t want to create an install link, you don’t have to include this array in your app manifest.

### Configure app permissions

In the `permissions` array, [include the necessary object and event permissions](https://docs.stripe.com/stripe-apps/reference/permissions.md) for your use case. For example, accessing the [Customers API](https://docs.stripe.com/api/customers.md) needs the `customer_read` permission.

- Enter each permission as an object with both a `permission` and a `purpose`. Stripe uses the `purpose` string during app review.
- Include only the permissions that your app needs.

## Implement server-side logic

You can implement back-end functionality such as:

- Integrating securely with external systems
- Handling Stripe events with webhooks
- Making signed Stripe API calls
- Scheduling actions

For detailed instructions, see [Add server-side logic](https://docs.stripe.com/stripe-apps/build-backend.md).

## Upload, test, and publish your app

The process for uploading, testing, and publishing your app depends on whether you want to publish your app to the Stripe App Marketplace or keep it private to your own account.

#### Public (Marketplace) app

### Upload your app

1. In the Stripe CLI, run `stripe login` to confirm that you’re logged into the correct Stripe account. Then run `stripe apps upload` to upload the app to your Stripe account.
1. In your Stripe Dashboard, open the **Developers** menu and select **Created apps**.
1. Click your app to open its details page, then select the **External test** tab.
1. Click **Get started** to set up an external test.
1. Copy the sandbox link.
1. In a new browser tab, load the sandbox link. It opens the app install page, which lists your app’s permissions.

### Enable sandbox testing

After you upload an app into your live account, Stripe auto-generates a managed sandbox account for testing. Your managed sandbox has its own API keys.

To test your app in the sandbox, [enable it for sandbox installation](https://docs.stripe.com/stripe-apps/enable-sandbox-support.md#api-keys).

### Publish your app

After Stripe completes the [app review](https://docs.stripe.com/stripe-apps/review-requirements.md) and approves the app for publication, you can publish it:

1. In your Stripe Dashboard, open the **Developers** menu and select **Created apps**.
1. Click your app to open its details page.
1. Under **Publish app**, click **Review and publish**.

Make sure to test your app completely before publishing it.

After you publish your app, it becomes discoverable on [marketplace.stripe.com](http://marketplace.stripe.com).

#### Private app

To test your app with sandbox data before installing it in live mode, upload and install it in your sandbox. When you want to install it in live mode, you need to upload and install it again.

1. In the Stripe CLI, run `stripe login` to confirm that you’re logged into the correct Stripe account.
   - To install your private app for testing with sandbox data, log into your sandbox account.
   - To install your private app in live mode, log into your regular Stripe account.
1. Run `stripe apps upload` to upload the app to your Stripe account.
1. In your Stripe Dashboard, open the **Developers** menu and select **Created apps**.
1. Click your app to open its details page.
1. In the **Publish app** section, select a version to install from the **Version** dropdown.
1. Wait for the **Install app** button to enable, then click it.

Any team members with access to your Stripe account can access your private app. To make an app available to anyone else, you need to make it public and publish it to the [Stripe App Marketplace](http://marketplace.stripe.com).


# OAuth 2.0

> This is a OAuth 2.0 for when app-auth-type is oauth. View the full page at https://docs.stripe.com/stripe-apps/back-end-app-example?app-auth-type=oauth.

The following example shows how to build a Stripe app that uses OAuth 2.0 authentication.

## Create a Stripe account

Before integrating with Stripe, you must create a Stripe account.

1. [Create an account](https://dashboard.stripe.com/register) by entering your email address, full name, country, and creating a password.
1. Fill out your business profile.
1. In the Dashboard, click **Verify your email**. Stripe sends a verification email to your email address.
1. Verify your email address.

> You can continue building your app in a sandbox as you follow the steps in this guide. You need a live Stripe account to publish your app.

## Install Stripe CLI and Apps CLI Plugin

#### javascript

```jsx
# Install Homebrew to run this command: https://brew.sh/
brew install stripe/stripe-cli/stripe
```

#### javascript

```jsx
# Connect the CLI to your dashboard
stripe login
```

#### javascript

```jsx
# Install Apps CLI Plugin
stripe plugin install apps
```

See the [additional instructions](https://docs.stripe.com/stripe-apps/create-app.md) to verify that you’re using CLI v1.12.4 and that node.js is up to date.

## Create your app

#### javascript

```jsx
stripe apps create {my-app-name}
```

After you run this command, it prompts you for the following:

- An app ID, which must be globally unique and can change
- An app display name, which doesn’t need to be unique and that you can change

## Configure your app

In your new directory, find the [stripe-app.json app manifest file](https://docs.stripe.com/stripe-apps/reference/app-manifest.md), and update it as follows:

#### javascript

```jsx
{
   "id": "com.example.example-app", // unique app ID
   "version": "0.0.1",  	 // app version
   "name": "Example App",  // app display name
   "icon": "./[YOUR_APP]_icon_32.png",	// app icon; put the file in the same directory for ease of distribution
   "stripe_api_access_type": "oauth",
   "allowed_redirect_uris": ["https://example.com/oauth/callback"], // redirect URLs
   "distribution_type": "public",
   "sandbox_install_compatible": "true",
   "permissions": []
}
```

### Configure installation redirect URLs

In the `allowed_redirect_uris` array, add the URLs to return your app users to after they install your app and authenticate with Stripe. The first entry becomes the default.

### Configure app permissions

In the `permissions` array, [include the necessary object and event permissions](https://docs.stripe.com/stripe-apps/reference/permissions.md) for your use case. For example, accessing the [Customers API](https://docs.stripe.com/api/customers.md) needs the `customer_read` permission.

- Enter each permission as an object with both a `permission` and a `purpose`. Stripe uses the `purpose` string during app review.
- Include only the permissions that your app needs.

## Implement server-side logic

You can implement back-end functionality such as:

- Integrating securely with external systems
- Handling Stripe events with webhooks
- Making signed Stripe API calls
- Scheduling actions

For detailed instructions, see [Add server-side logic](https://docs.stripe.com/stripe-apps/build-backend.md).

## Enable your app to use OAuth API tokens

When users install your app, they’re redirected back to your site. The callback URL receives an OAuth [authorization](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1) code that your app can exchange for an API access token and a refresh token. This code expires after 5 minutes and can only be used once. To use the code, run the following command using an [OAuth client library](https://oauth.net/code/):

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

The response includes two tokens:

- `access_token`: use the access token to call the Stripe API on behalf of the app user
- `refresh_token`: [exchange the refresh token for a new access token](https://docs.stripe.com/stripe-apps/api-authentication/oauth.md#refresh-access-token)

Access tokens expire after 1 hour, and refresh tokens expire after 1 year. Each time you exchange a refresh token for a new access token, the response also includes a new refresh token with a 1-year expiration. As long as you request a new access token within 1 year of the last request, your refresh tokens never expire.

#### javascript

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

## Upload, test, and publish your app

#### Public (Marketplace) app

### Upload your app

1. In the Stripe CLI, run `stripe login` to confirm that you’re logged into the correct Stripe account. Then run `stripe apps upload` to upload the app to your Stripe account.
1. In your Stripe Dashboard, open the **Developers** menu and select **Created apps**.
1. Click your app to open its details page, then select the **External test** tab.
1. Click **Get started** to set up an external test.
1. Copy the sandbox link in the **Test OAuth** section.
1. In a new browser tab, load the sandbox link. You can use it to test with different accounts.

### Enable sandbox testing

After you upload an app into your live account, Stripe auto-generates a managed sandbox account for testing. Your managed sandbox has its own API keys.

To test your app in the sandbox, [enable it for sandbox installation](https://docs.stripe.com/stripe-apps/enable-sandbox-support.md#api-keys).

### Publish your app

After Stripe completes the [app review](https://docs.stripe.com/stripe-apps/review-requirements.md) and approves the app for publication, you can publish it:

1. In your Stripe Dashboard, open the **Developers** menu and select **Created apps**.
1. Click your app to open its details page.
1. Under **Publish app**, click **Review and publish**.

Make sure to test your app completely before publishing it.

After you publish your app, it becomes discoverable on [marketplace.stripe.com](http://marketplace.stripe.com).


# Restricted API key (RAK)

> This is a Restricted API key (RAK) for when app-auth-type is rak. View the full page at https://docs.stripe.com/stripe-apps/back-end-app-example?app-auth-type=rak.

The following example shows how to build a Stripe app that uses RAK authentication.

## Create a Stripe account

Before integrating with Stripe, you must create a Stripe account.

1. [Create an account](https://dashboard.stripe.com/register) by entering your email address, full name, country, and creating a password.
1. Fill out your business profile.
1. In the Dashboard, click **Verify your email**. Stripe sends a verification email to your email address.
1. Verify your email address.

> You can continue building your app in a sandbox as you follow the steps in this guide. You need a live Stripe account to publish your app.

## Install Stripe CLI and Apps CLI Plugin

#### javascript

```jsx
# Install Homebrew to run this command: https://brew.sh/
brew install stripe/stripe-cli/stripe
```

#### javascript

```jsx
# Connect the CLI to your dashboard
stripe login
```

#### javascript

```jsx
# Install Apps CLI Plugin
stripe plugin install apps
```

See the [additional instructions](https://docs.stripe.com/stripe-apps/create-app.md) to verify that you’re using CLI v1.12.4 and that node.js is up to date.

## Create your app

#### javascript

```jsx
stripe apps create {my-app-name}
```

After you run this command, it prompts you for the following:

- An app ID, which must be globally unique and can change
- An app display name, which doesn’t need to be unique and that you can change

## Configure your app

In your new directory, find the [stripe-app.json app manifest file](https://docs.stripe.com/stripe-apps/reference/app-manifest.md), and update it as follows:

#### javascript

```jsx
{
   "id": "com.example.example-app", // unique app ID
   "version": "0.0.1",  	 // app version
   "name": "Example App",  // app display name
   "icon": "./[YOUR_APP]_icon_32.png",	// app icon; put the file in the same directory for ease of distribution
   "stripe_api_access_type": "restricted_api_key",
   "allowed_redirect_uris": ["https://example.com/installed/callback"], // optional redirect URLs
   "distribution_type": "public", // for a private app, set to "private"
   "sandbox_install_compatible": "true",
   "permissions": []
}
```

### Default RAK authentication

When a user installs an app that uses RAK authentication but no UI extensions, [Stripe opens the app settings page](https://docs.stripe.com/stripe-apps/api-authentication/rak.md#user-experience) so they can generate and store publishable and restricted keys.

### Configure installation redirect URLs (optional)

In the `allowed_redirect_uris` array, add the URLs to return your app users to after they install your app from an [install link](https://docs.stripe.com/stripe-apps/install-links.md). The first entry becomes the default. If you don’t want to create an install link, you don’t have to include this array in your app manifest.

### Configure app permissions

In the `permissions` array, [include the necessary object and event permissions](https://docs.stripe.com/stripe-apps/reference/permissions.md) for your use case. For example, accessing the [Customers API](https://docs.stripe.com/api/customers.md) needs the `customer_read` permission.

- Enter each permission as an object with both a `permission` and a `purpose`. Stripe uses the `purpose` string during app review.
- Include only the permissions that your app needs.

## Implement server-side logic

You can implement back-end functionality such as:

- Integrating securely with external systems
- Handling Stripe events with webhooks
- Making signed Stripe API calls
- Scheduling actions

For detailed instructions, see [Add server-side logic](https://docs.stripe.com/stripe-apps/build-backend.md).

## Upload, test, and publish your app

The process for uploading, testing, and publishing your app depends on whether you want to publish your app to the Stripe App Marketplace or keep it private to your own account.

#### Public (Marketplace) app

### Upload your app

1. In the Stripe CLI, run `stripe login` to confirm that you’re logged into the correct Stripe account. Then run `stripe apps upload` to upload the app to your Stripe account.
1. In your Stripe Dashboard, open the **Developers** menu and select **Created apps**.
1. Click your app to open its details page, then select the **External test** tab.
1. Click **Get started** to set up an external test.
1. Copy the sandbox link.
1. In a new browser tab, load the sandbox link. It opens the app install page, which lists your app’s permissions.

### Enable sandbox testing

After you upload an app into your live account, Stripe auto-generates a managed sandbox account for testing. Your managed sandbox has its own API keys.

To test your app in the sandbox, [enable it for sandbox installation](https://docs.stripe.com/stripe-apps/enable-sandbox-support.md#api-keys).

### Publish your app

After Stripe completes the [app review](https://docs.stripe.com/stripe-apps/review-requirements.md) and approves the app for publication, you can publish it:

1. In your Stripe Dashboard, open the **Developers** menu and select **Created apps**.
1. Click your app to open its details page.
1. Under **Publish app**, click **Review and publish**.

Make sure to test your app completely before publishing it.

After you publish your app, it becomes discoverable on [marketplace.stripe.com](http://marketplace.stripe.com).

#### Private app

To test your app with sandbox data before installing it in live mode, upload and install it in your sandbox. When you want to install it in live mode, you need to upload and install it again.

1. In the Stripe CLI, run `stripe login` to confirm that you’re logged into the correct Stripe account.
   - To install your private app for testing with sandbox data, log into your sandbox account.
   - To install your private app in live mode, log into your regular Stripe account.
1. Run `stripe apps upload` to upload the app to your Stripe account.
1. In your Stripe Dashboard, open the **Developers** menu and select **Created apps**.
1. Click your app to open its details page.
1. In the **Publish app** section, select a version to install from the **Version** dropdown.
1. Wait for the **Install app** button to enable, then click it.

Any team members with access to your Stripe account can access your private app. To make an app available to anyone else, you need to make it public and publish it to the [Stripe App Marketplace](http://marketplace.stripe.com).