Stripe Apps
StripeOfficialPublished by Stripe
- Skill
- Tool integration
- Software development
- MIT
- No issues found
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
This skill provides a structured approach to developing and maintaining Stripe Apps. It guides users through selecting the correct extension architecture, implementing authentication, building UI components, and managing backend services or webhooks. By leveraging bundled reference files and canonical documentation, it ensures that app development follows Stripe's best practices for security, configuration, and lifecycle management.
What it does
- Provides guidance on selecting the appropriate Stripe extension interface.
- Assists in building and modifying Stripe Dashboard UI components.
- Supports the implementation of backend services, webhooks, and secret storage.
- Helps determine the correct authentication method for Stripe API access.
- Offers instructions for testing, debugging, and publishing Stripe Apps.
- Clarifies the applicability of extensions for specific billing or workflow requirements.
When to use it
- When you need to build a custom UI extension for the Stripe Dashboard.
- When deciding between Restricted API keys, Platform keys, or OAuth for your app.
- When implementing backend logic or handling Stripe events via webhooks.
- When you need to store sensitive credentials securely using the Secret Store API.
- When troubleshooting or modifying an existing Stripe App's manifest or configuration.
Advantages
- Ensures alignment with official Stripe development patterns and security standards.
- Reduces development time by providing clear paths to relevant documentation.
- Helps prevent common architectural errors in app authentication and event handling.
- Provides a consistent workflow for the entire app lifecycle from scaffolding to release.
Usage examples
- “How do I determine if my Stripe App needs a backend?”
- The agent will reference the backend documentation to explain that a backend is required for long-term data storage, server-side secrets, or handling webhooks, while suggesting the Secret Store API for simpler needs.
- “Help me choose the right authentication type for a private Stripe App.”
- The agent will compare Restricted API keys, Platform keys, and OAuth, recommending Restricted API keys as the simplest and most secure choice for private integrations.
Install
Download the skill as a ZIP:
https://autogineer.com/agent-skills/stripe/stripe-apps/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip stripe-apps.zip -d .agents/skills
Documentation by Stripe
Stripe Apps
Select and read the existing guidance for the user’s task. Product documentation describes what an extension can do; implementation guides describe how to build it. Before recommending an extension or writing code, load the applicable bundled reference files as well as the relevant product documentation. A link or filename in this skill isn’t a substitute for reading its contents.
For a capability question, check native Stripe features and the documented applicability and limitations of the extension. For an implementation request, create or modify working files using the selected guide. For an existing app, inspect its manifest, packages, installed SDK, and local agent instructions before deciding what to change.
Choose the relevant documentation
Use information already supplied by the user or existing app. Read <references/discovery.md> when you need to clarify the app’s requirements, and <references/extension-types.md> for an overview of app architectures. Ask only for missing information that affects the task.
Product capabilities
Use these existing product documents to determine which capability fits and whether the account has the required access. Don’t infer support from an extension’s name or the existence of a scaffold.
| Task | Read |
|---|---|
| Select an extension interface and its supported implementation types | Extension points and how extensions work |
| Change how items are included on subscription invoices | Item handling extensions |
| Customize prorations | Native proration behavior and prorations extensions |
| Apply customer balances | Customer balance extensions |
| Calculate discount amounts | Discount calculation extensions |
| Add an action to Stripe Workflows | Existing workflow actions, existing custom actions, and how custom actions work |
| Customize another product’s behavior | Follow the selected interface’s product documentation from the extension-point catalog |
Implementation guidance
The references/*.md files are bundled with this skill. After selecting the capability, load the applicable files before following their links to supporting documentation. Combine rows when an app needs multiple types. Follow the selected guide’s prerequisites, scaffolding, testing, and debugging instructions.
| Task | Read |
|---|---|
| Build or modify any Dashboard UI, including drawers and full-page apps | <references/ui-extensions.md>, then each selected component’s current API documentation |
| Author, test, or debug a script extension | <references/script-extensions.md>, then the selected extension point’s implementation guide |
| Build a custom-action script | <references/script-extensions.md> and build a custom action with a script |
| Build a custom-action remote function | Build a custom action with a remote function |
| Build a self-hosted UI back-end or webhook service | <references/backend.md> and <references/authentication.md>; also load <references/webhooks.md> when receiving Stripe events |
| Store app credentials with the Secret Store API | The Secret Store API section in <references/backend.md> and store secrets, including for apps without a self-hosted back-end |
| Look up APIs, SDK patterns, configuration, or additional extension documentation | <references/canonical-docs.md> |
Use the UI reference for layout and composition, and current component documentation for import paths, props, and styling APIs. For scripts and remote functions, follow the selected extension’s documentation; UI and self-hosted back-end instructions don’t define their runtime capabilities.
Shared app lifecycle
Read these references when the corresponding task is needed. Reuse existing apps and packages; scaffold only what is missing.
| Task | Read |
|---|---|
| Scaffold, build, test, preview, or upload an app | <references/workflow.md>, together with the selected implementation guide |
| Choose authentication for access to Stripe APIs | <references/authentication.md> |
| Receive Stripe events | <references/webhooks.md> |
| Build a first-run setup experience | <references/onboarding-ux.md> and the UI reference |
| Release versions, change installed permissions, or publish to the marketplace | <references/publishing.md> |
| Submit feedback after running app toolchain commands | <references/feedback.md> |
Load bundled reference files
Use the task tables to select every applicable bundled reference under
references/, then open those files with a file-reading tool before starting the corresponding work. For example, UI with a self-hosted back-end needs both UI and back-end guidance; onboarding also needs the UI reference.Follow relevant pointers to other bundled references inside the files you load, including filenames written as code rather than links. For example, back-end guidance can require authentication guidance, and changing permissions can require publishing guidance. Use this skill’s direct links to locate those files.
Read the canonical documentation required by those references. External documentation supplements the bundled guidance on workflow, layout, and other task-specific decisions.
Resolve
references/paths relative to this skill’s directory and bare reference filenames relative to itsreferences/directory. When reading the hosted skill, fetch the corresponding reference URLs relative to the skill URL.Load only references relevant to the task, and reuse contents already read during the session unless they have changed. A full-stack app doesn’t require every document in the skill.
Read canonical pages using the available documentation tools. Prefer
stripe docswhen available, including for pages that require account access.Use current product documentation and the installed SDK’s types for API contracts and limitations. If an example in a reference disagrees, check the version and follow the applicable canonical documentation.
Read any interface-specific agent instructions supplied with an existing or newly generated extension. If none are present, use the linked product and implementation guides.
If the documentation doesn’t establish that an extension meets a requirement, state what is unknown or unsupported before proceeding.
Keep the work within the user’s request. Report the changes, validation results, and remaining steps relevant to that app.
Files
- ATTRIBUTION.mdAdded by AutoGineer819 B
- LICENSELicence file added by AutoGineer1.1 KiB
- SKILL.md7.6 KiB
- references/authentication.md4.6 KiB
- references/backend.md4.4 KiB
- references/canonical-docs.md4.4 KiB
- references/discovery.md9.2 KiB
- references/extension-types.md5.1 KiB
- references/feedback.md1.9 KiB
- references/onboarding-ux.md2.7 KiB
- references/publishing.md5.7 KiB
- references/script-extensions.md7.3 KiB
- references/ui-extensions.md20.7 KiB
- references/webhooks.md3.4 KiB
- references/workflow.md8.3 KiB
references/authentication.md
Authentication — platform keys, OAuth, restricted API keys
Authentication
How your app authenticates and accesses Stripe data for merchants who install it.
Canonical page: https://docs.stripe.com/stripe-apps/api-authentication
Read this page using an available documentation tool before implementing authentication patterns.
Three authentication types
Stripe Apps supports three authentication methods, configured via stripe_api_access_type in the app manifest:
| Auth type | Manifest value | How it works | Best for |
|---|---|---|---|
| Restricted API key (recommended) | restricted_api_key | Stripe generates a scoped key at install; merchant provides it to your system | Private apps, simpler integrations, apps that don’t need Connect-style access |
| Platform keys | platform | Your secret key + Stripe-Account header to act on behalf of installers | Public/marketplace apps that need to act across many merchants |
| OAuth 2.0 | oauth | Standard OAuth flow generates access tokens per-account | Apps where merchant must be merchant-of-record |
Choosing the right type
Default to restricted API keys unless you have a specific reason to use platform keys or OAuth. RAKs are simpler, more secure (scoped permissions), and don’t create a Connect-style relationship.
Use a different type when:
You need Connect webhook fanout (events from all merchants to one endpoint): Platform keys.
You’re building a public marketplace app acting across many merchants: Platform keys.
The merchant must be the merchant-of-record for charges: OAuth.
Private app or fewer merchants, no Connect fanout needed: Restricted API keys (simplest).
Platform keys
Your app’s API key acts on behalf of a merchant’s account using the Stripe-Account header:
// Use a restricted API key when possible; fall back to secret key only for platform-key apps
const stripe = require("stripe")(process.env.STRIPE_API_KEY);
await stripe.customers.list({}, {
stripeAccount: "acct_xxxxx", // the merchant's account ID
});How to get the merchant’s account ID:
From a webhook event:
event.accountFrom
fetchStripeSignaturepayload: the signed data includesaccount_idFrom the UI extension:
userContext.account.id(top-level prop)
Key fact: Platform keys use the same Stripe-Account header mechanism as Stripe Connect. Installers are NOT onboarded as connected accounts in the traditional sense — the header simply authorizes your key to access their account within the app’s declared permissions.
OAuth 2.0
Use OAuth when the connected account needs to be the merchant of record for charges, or when you need the merchant’s own Stripe identity on API calls.
Most apps do NOT need OAuth. Use platform keys unless you specifically need this.
For implementation, read: https://docs.stripe.com/stripe-apps/pkce-oauth-flow
Restricted API keys
With RAK apps, Stripe generates a restricted key at install time with only the permissions your app declared. The merchant copies this key to your system.
Key differences from platform keys:
No Connect-style relationship is created
Can’t use Connect webhook fanout (each merchant manages their own webhooks)
Simpler model for private apps or apps with fewer merchants
Authenticating the UI to your backend (fetchStripeSignature)
fetchStripeSignature proves to your backend that a request came from a legitimate app installation.
Key facts:
The signed payload contains
user_idandaccount_idby default (field order matters)You can include additional data by passing it to
fetchStripeSignature(extraPayload)Backend verifies with
stripe.webhooks.signature.verifyHeader()The signing secret (starts with
absec_...) is generated on firststripe apps upload
For the full implementation pattern, read: https://docs.stripe.com/stripe-apps/build-backend
Identifying the installing merchant
When a merchant installs your app, Stripe sends an account.application.authorized event. When they uninstall, it sends account.application.deauthorized.
Store the account ID from event.account to make future API calls on their behalf.
Permission scopes
Use the CLI to add permissions to your app:
stripe apps grant permission "customer_read" "Read customer data to show in the Dashboard"
stripe apps grant permission "event_read" "Receive webhook events"This updates stripe-app.yaml with the correct format automatically.
When you change permissions: existing users must re-authorize. The app returns an invalid-request error for undeclared permissions until the user re-authorizes. See publishing.md for details.
Requirements and compatibility
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Security
No issues found by our static scan· No issues found
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Published by
- Stripe
- Publisher
- Stripe (Official)
- Source
- stripe/ai · skills/stripe-apps · commit 38fa045
- Licence
- MIT License (redistribution allowed)
- LICENSE (added by AutoGineer from LICENSE)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
- Also distributed in
- stripe/ai, stripe/ai, stripe/ai, stripe/ai, stripe/ai
AutoGineer is not affiliated with or endorsed by Stripe or Stripe.
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download stripe-apps.zip