# Restricted API key authentication

Generate a permissioned restricted API key (RAK) when a user installs your app.

Stripe Apps can use restricted API keys (RAKs) for authenticating with Stripe APIs. These apps provide users with a RAK with specific permissions after they install the app.

If your integration previously relied on users to provide their secret key, you might be able to use a RAK Stripe App as a replacement. Because RAKs work in the same manner as secret keys, using them for authorization might require no changes to your back-end code.

### RAK authentication benefits

- The key generated by the app contains only the necessary permissions for the app to function, which gives users more secure control of their account’s data.
- Because the app already has defined permissions, installing users don’t need to manually select permissions to add it to the restricted key. Users only need to install the app and click a button to generate the key.

### RAK authentication limitations

- Using RAK authentication requires at least some user interaction. Users must generate the key through the app and provide it to a partner or an integration.
- When using RAK authentication for your app, UI extensions might not function properly. It supports the [app settings page](https://docs.stripe.com/stripe-apps/app-settings.md), but UI Extensions won’t have access to additional Dashboard context.

## Installation

A user installing a Stripe App that uses RAK authentication follows these steps:

1. From the App Marketplace or through an [install link](https://docs.stripe.com/stripe-apps/install-links.md), the user selects the appropriate account and accepts permissions for installing the app.
2. After installing the app, we redirect the user to the settings page for the app to generate a restricted API key, provisioned with the proper permissions.
![The "View API Keys" button on the settings page for a RAK app](https://b.stripecdn.com/docs-statics-srv/assets/view-app-keys-button.226d90da9686e24a146d50c7371c4a28.png)

1. The user copies the generated key and provides the key to your site.
![Copying the app keys from settings page](https://b.stripecdn.com/docs-statics-srv/assets/copy-app-keys.89fd5ca5d68b91c105164092b4de5029.png)

## Develop your app

1. [Install the Stripe Apps CLI plugin](https://docs.stripe.com/stripe-apps/create-app.md#install-stripe-apps-cli) (if you haven’t already done so).

2. Create your app using our template.

   ```bash
   stripe apps create <app-name> --template restricted-api-key-app
   ```

   If you have an existing app, run this command in Stripe CLI:

   ```bash
   stripe apps set api-access-type restricted_api_key
   ```

3. Add all the [permissions](https://docs.stripe.com/stripe-apps/reference/permissions.md) that your app requires.

4. Edit your [app settings page](https://docs.stripe.com/stripe-apps/app-settings.md). If you use the template above, a settings view is automatically created. We recommend adding instructions or links to your own documentation on this page for users to reference when setting up your app.
![The install link page showing app permissions](https://b.stripecdn.com/docs-statics-srv/assets/settingsview.ca0e43bcc311ea9819da61b2949e6ed1.png)
   
   Example app settings page

5. [Upload](https://docs.stripe.com/stripe-apps/upload-install-app.md) your app to Stripe.

   > After you upload your RAK app, you can’t change the [API authentication method](https://docs.stripe.com/stripe-apps/api-authentication.md).

   ```bash
   stripe apps upload
   ```

## Test your app

You can test the RAK authentication on your own account.

Install the app in a general sandbox using the path for its distribution type:

- **Private app**: Use the Stripe CLI to log in to the sandbox and upload the app. Then, in the sandbox Dashboard, go to [Created apps](https://dashboard.stripe.com/test/apps/created), select your app, open the **Versions** tab, and click **Install** or **Change version**.
- **Public app**: [Enable general sandbox support](https://docs.stripe.com/stripe-apps/enable-sandbox-support.md), upload the updated app to your live account, and [create an external test link](https://docs.stripe.com/stripe-apps/test-app.md) for that version. Open a general sandbox, then visit the external test link to install the app in that sandbox.

1. In the sandbox Dashboard, go to your [installed apps page](https://dashboard.stripe.com/settings/apps) and select the app.

2. On the app settings page, click **View API keys**.

   In a sandbox, click **Reveal key** to view the restricted API key.

   In live mode, click **Generate new key** to view the key for the first time. You can’t view a live mode key again after you close the dialog.

   Click **Roll key** to replace it.

3. Copy the key and store it securely (for example in an environment variable or a secrets manager) to test your integration. Don’t embed the key in your code. See [best practices for managing secret keys](https://docs.stripe.com/keys-best-practices.md).

When you install the app in the account you used to create it, the restricted API key has only the permissions that your app requests, not all the permissions of your account.

If you installed the app in your own account and **View API keys** shows only the publishable key, the installation doesn’t have a restricted API key. To provision one, either upload a new version of your app and install that version, or uninstall your app, wait for the uninstall to finish, and reinstall the same version. To install, go to [Created apps](https://dashboard.stripe.com/apps/created), select your app, open the **Versions** tab, and install the version you want to use. Use the same account or sandbox and mode as the installation that’s missing the key.

If you’re developing a public app, use [external testing](https://docs.stripe.com/stripe-apps/test-app.md) to test it on a different Stripe account than the one used to develop it.