Stripe – Configuration Guide
Stripe is a payment processing platform that enables businesses to accept online payments, manage billing, and handle subscriptions.
How to create OAuth credentials for Stripe
The Apideck Stripe connector authenticates through a Stripe App that you build and own, with OAuth enabled. Your consumers install that app on their own Stripe account, and Apideck exchanges the resulting authorization code for tokens on your behalf.
Obtaining the credentials is therefore a small build rather than a portal form: you create the app with the Stripe CLI, set a few fields in its manifest, upload it, and then copy three values into the Apideck Stripe connector settings.
Apideck publishes a working reference app you can copy from: apideck-samples/stripe-app.
Before you start
You will need:
- A Stripe account. Sign up free at dashboard.stripe.com/register. Publishing to the Stripe App Marketplace later additionally requires an activated account, and a Connect platform account cannot publish (see Scaling beyond external testing), so pick the owning account with that in mind.
- A developer (or a developer's help) and the local tooling Stripe requires for Stripe Apps: the Stripe CLI, Node.js and pnpm. Stripe lists the current prerequisites and supported versions on Getting started with Stripe Apps and the Stripe CLI install page.
- Access to your Apideck Dashboard to save the credentials.
1. Install the Stripe CLI and the Apps plugin
Install the Stripe CLI, then log in so the CLI is paired with your Stripe account:
Stripe Apps commands come from CLI plugins, so install both the apps plugin and the generate plugin Stripe now uses to scaffold new apps:
Stripe documents the exact prerequisites and any additional plugins on Getting started with Stripe Apps. Follow that page rather than pinning tool versions, since Stripe moves them regularly.
2. Create the app
Stripe's OAuth guide still shows the previous form stripe apps create your-app-name; follow the Getting started with Stripe Apps page, which is the current one. The CLI prompts for two things:
- ID: how Stripe identifies your app. It must be globally unique.
- Display name: the name Stripe displays for your app. Pick something your consumers will recognise as yours; Stripe lets you change the name later.
If you intend to publish the app on the Stripe App Marketplace at any point, note Stripe's naming rules for public apps (see Scaling beyond external testing below).
3. Configure the manifest for OAuth
Open the generated stripe-app.json and set the following fields. The first three turn an ordinary Stripe App into one Apideck can authenticate through; the fourth is optional:
| Manifest field | Value | Why |
|---|---|---|
stripe_api_access_type | "oauth" | Makes the app authenticate through OAuth instead of only running inside the Dashboard. |
distribution_type | "public" | Required for OAuth apps. It makes OAuth installation possible; it does not publish the app or list it anywhere. |
allowed_redirect_uris | must include "https://unify.apideck.com/vault/callback" | Where Stripe returns the consumer after they install the app. |
sandbox_install_compatible | true | Only needed if you want the app to be installable in Stripe sandboxes. |
Redirect URL. The value Apideck listens on is always:
https://unify.apideck.com/vault/callback
Stripe uses the first entry in allowed_redirect_uris as the default redirect, so list the Apideck callback first. The sample app's manifest does exactly that. Stripe also requires live-mode redirect URIs to use HTTPS, which the Apideck callback does.
Stripe's own field-by-field reference is Stripe Apps: OAuth 2.0 and the app manifest reference.
4. Grant the permissions the connector needs
Stripe Apps declare their access as a list of permissions in the manifest, and the consumer sees that list on the install screen. Stripe Apps OAuth has no per-request scopes, so whatever the manifest declares is what the connection can do: a permission you leave out becomes a failing call later, and adding one afterwards means uploading a new version of the app and asking your users to re-authorise it.
Broadly, the connector needs read and write access to the Stripe resources it maps (customers, invoices, invoice items, products, credit notes, charges and payment intents, refunds, tax rates), read access to the account itself, and the ability to manage webhook endpoints so Apideck can register event subscriptions for each connection.
Rather than assembling that list by hand, copy the permissions array from the sample app's manifest, which is the working reference for this connector. Stripe's permissions reference documents what each individual permission grants if you want to trim the list for your own use case.
5. Upload the app
Each upload creates a new version of the app. You will select a version when you set up the install link in the next step, so re-upload whenever you change permissions or redirect URIs, and then point the link at the new version.
6. Get your install link and the three Apideck values
The install link the connector uses comes from the app's External test tab.
- In the Stripe Dashboard, open Developers → Apps and select your app.
- Open the External test tab and click Get started.
- Choose Link access (anyone with the link, or only people you invite) and select the app version to serve.
- Save. Stripe now shows install links under Test OAuth, with separate links for live mode, test mode and sandboxes.
- Copy the link for the mode you want to configure. It looks like this:
https://marketplace.stripe.com/oauth/v2/chnlink_XXXXXXXX/authorize?client_id=ca_XXXXXXXX
Two of the three values you need are inside that link. Then open the Apideck Stripe connector settings and fill in, under OAuth Configuration:
| Apideck Dashboard field | What to enter | Where it comes from |
|---|---|---|
| Client ID | ca_... | The client_id query parameter of the install link. |
| Client Secret | sk_test_... or sk_live_... | Your Stripe secret API key, from Developers → API keys. Not a value from the link. |
| Channel Link ID | chnlink_... | The path segment of the install link between /oauth/v2/ and /authorize. |
The Client Secret is a secret key, not an app secret. Stripe's token endpoint authenticates the code exchange with the app developer's secret API key, so that is what Apideck stores in the Client Secret field. Treat it accordingly: it is a full-access credential for your own Stripe account.
Save the configuration. Consumers can now authorize the connector from Vault; they install your app on their Stripe account and are returned to the Apideck callback, and Apideck handles the code exchange and all subsequent token refreshes. There is nothing for a consumer to paste in, and no callback handler for you to build.
7. Match the mode of the link and the key
Stripe keeps test-mode, sandbox and live-mode data fully separate, and the code exchange must be authenticated with a key from the same mode as the install link.
| Environment | Install link | Client Secret to use |
|---|---|---|
| Test mode | The test-mode link from Test OAuth | Your test-mode secret key (sk_test_...) |
| Sandbox | The sandbox link from Test OAuth (requires sandbox_install_compatible: true) | The sandbox's secret key |
| Live mode | The live-mode link from Test OAuth | Your live-mode secret key (sk_live_...) |
A mismatch (for example a test-mode link with a live-mode key) fails at the token exchange, so the connection never completes. If you want to try the connector before going live, configure the test-mode pair first and switch both values together when you move to live mode.
Keep the secret key you configured valid: Stripe authenticates token refreshes with the same key, so if you roll or delete it, update the Client Secret in the Apideck Dashboard at the same time.
8. Scaling beyond external testing
External testing is Stripe's distribution route for an app that has not been through review, and Stripe applies its own rules to it:
- A limit of 25 testers per app. Each Stripe account that installs your app counts as one tester.
- The app is shown as a test version, and Stripe requires you to tell your users that the app is still in development and has not been reviewed by Stripe.
To move past those rules, submit the app to the Stripe App Marketplace. Stripe's publishing guide covers the process; the requirements worth knowing before you build are:
- Stripe reviews the submission and replies with approval or feedback by email; Stripe states this takes 4 business days.
- Your Stripe account must be activated, with a verified email address and business details, and your business must not be on Stripe's Prohibited and Restricted Businesses list.
- A Connect platform account cannot publish an app on the Stripe Marketplace (stated on Stripe's Getting started with Stripe Apps page). If your company runs a Connect platform, decide up front which Stripe account will own the app.
- One public app per Stripe account. Marketplace listings are English only.
- The listed name is limited to 35 characters, cannot contain the words Stripe, app, free or paid, and must match the manifest
name.
Any change to the app or its listing after approval means resubmitting for review.
9. Webhooks: nothing to register
You do not create webhook endpoints for this connector. Apideck registers the Stripe webhook endpoint for each connection automatically once that connection becomes callable, and removes it when the connection is disabled or deleted. The only thing you have to do is make sure your app's manifest grants the webhook-endpoint permissions (step 4); without them, registration cannot happen.
FAQ and troubleshooting
Does distribution_type: "public" make my app public?
No. It is a manifest requirement for OAuth apps and only enables OAuth installation. Your app is not listed anywhere until you submit it to the Stripe App Marketplace and Stripe approves it.
The install link has no chnlink_ segment.
You are looking at the wrong link. The Settings tab shows the public Marketplace links (.../oauth/v2/authorize?client_id=ca_...), which do not work until the app is published. Take the link from the External test tab's Test OAuth section instead; that is the one whose path contains the Channel Link ID.
Authorization fails at the end of the flow.
Check the three usual causes, in order: the Client Secret is a secret key from the same mode as the install link; https://unify.apideck.com/vault/callback is present in allowed_redirect_uris in the uploaded version of the app (a manifest change only takes effect after stripe apps upload and pointing the external-test link at the new version); and the Channel Link ID and Client ID were copied from the same link.
Who can install the app? Stripe requires administrator rights on the Stripe account to install a Stripe App, so each tester needs an administrator on their side.
A tester already has the published version of the app installed. Stripe does not allow both at once. The published version has to be uninstalled before the test version can be installed on that account.
I changed the permissions. Do existing connections get them? Not automatically. Stripe moves current testers to the version you select in the External test settings, but when that version changes the permissions, Stripe prompts each user by email and in their Dashboard to re-authorise the app and approve the new permissions. Until they do, calls that need a new permission fail.
I do not see the External test tab.
Stripe only shows it for apps with public distribution. Check that distribution_type is "public" in the uploaded version of the manifest.
Still stuck? Contact Apideck Support.