fcakyon/claude-codex-settings / plugins/stripe-skills/skills/stripe-apps
stripe-apps
VerifiedBuild, modify, or review Stripe Apps and extensions using the relevant documentation and reference guides. Use for custom Stripe Dashboard UI, stripe-app.yaml, @stripe/ui-extension-sdk, @stripe/extensibility-sdk, script extensions, extension interfaces, custom workflow actions, and apps that authenticate to Stripe or react to events. Also use when deciding whether a Stripe extension can support the user's billing or workflow requirements.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.6 KB |
| references/authentication.md | markdown | 4.6 KB |
| references/backend.md | markdown | 4.4 KB |
| references/canonical-docs.md | markdown | 4.4 KB |
| references/discovery.md | markdown | 9.2 KB |
| references/extension-types.md | markdown | 5.1 KB |
| references/feedback.md | markdown | 1.9 KB |
| references/onboarding-ux.md | markdown | 2.7 KB |
| references/publishing.md | markdown | 5.7 KB |
| references/script-extensions.md | markdown | 7.3 KB |
| references/ui-extensions.md | markdown | 20.7 KB |
| references/webhooks.md | markdown | 3.4 KB |
| references/workflow.md | markdown | 8.5 KB |
references/backend.md
View on GitHub# Backend — when and how to add server-side logic
## When you need a backend
You need a backend if your app needs to:
- Store data long-term (user preferences, linked accounts, custom records)
- Call APIs that require server-side secrets (API keys that can’t be in the browser)
- Run logic when the user isn’t in the Dashboard (webhooks, scheduled jobs)
- Call third-party services securely (email providers, CRMs, spreadsheet APIs)
- Perform actions that take longer than the UI can wait for
**You don’t need a backend if:**
- Your app only reads and displays Stripe data (use the SDK client directly in the UI)
- You only need to store a small amount of sensitive data — use the Secret Store API instead
## Canonical documentation
Before writing back-end code, read these pages using an available documentation tool:
| Topic | URL |
| --- | --- |
| Backend implementation + fetchStripeSignature | https://docs.stripe.com/stripe-apps/build-backend |
| Authentication types (determines backend pattern) | https://docs.stripe.com/stripe-apps/api-authentication |
| Events and webhooks | https://docs.stripe.com/stripe-apps/events |
| Secret Store API | https://docs.stripe.com/stripe-apps/store-secrets |
## Backend architecture decisions
### Authentication type determines the backend pattern
Your app’s `stripe_api_access_type` controls how the backend authenticates. See `authentication.md` for the full breakdown of auth types and when to use each one.
### CORS configuration
CORS (`Access-Control-Allow-Origin: *`) is needed ONLY on endpoints called by the UI extension. The UI runs in a sandboxed iframe with a `null` origin — specific origin allowlisting won’t work.
Webhook endpoints do NOT need CORS — they receive requests from Stripe’s servers, not from the browser.
### fetchStripeSignature verification
`fetchStripeSignature` is how the UI extension authenticates requests to your backend. The signed payload and verification method are documented at https://docs.stripe.com/stripe-apps/build-backend.
Key facts:
- The signing secret (starts with `absec_...`) is generated on first `stripe apps upload`
- The default signed payload contains `user_id` and `account_id` (field order matters)
- Extra data can be included by passing it to `fetchStripeSignature(payload)`
- Verification uses `stripe.webhooks.signature.verifyHeader()`
### Webhook configuration
Webhook setup depends on your app’s distribution and auth type:
| App type | Webhook setup |
| --- | --- |
| Private (your account only) | ONE standard webhook endpoint |
| Public with platform keys | ONE webhook with “Listen to events on Connected accounts” enabled |
| Public with restricted API keys | Can’t use Connect webhook fanout — each merchant manages their own webhooks |
The `event_read` permission MUST be declared in your manifest, plus read permissions for each event type you want to receive.
Read https://docs.stripe.com/stripe-apps/events for the full setup guide.
For firewall allowlisting of inbound webhook traffic, see https://docs.stripe.com/ips for Stripe’s IP addresses.
## Secret Store API
**Plain-language:** “Stripe has a built-in secure place to store passwords, tokens, and API keys for your app — you don’t need to build your own database for secrets.”
### Two scopes
| Scope | Use for | Example |
| --- | --- | --- |
| `account` | Shared across all users of an account | The business’s API key for an email service |
| `user` | Per-user secrets | An individual user’s OAuth access token |
### Limits and restrictions
- Maximum **10 secrets per scope** (account and user separately)
- Always list and delete before adding more if approaching the limit
- Do **not** store PCI-sensitive data (card numbers, CVVs, bank account numbers)
### Declaring the permission
In `stripe-app.yaml`:
```yaml
declarations:
stripe_api_access:
permissions:
- permission: secret_write
purpose: Store third-party credentials for the app
```
### Implementation
For the correct code patterns to read, write, and delete secrets, read: https://docs.stripe.com/stripe-apps/store-secrets
## Local development with a backend
Run your backend locally alongside `stripe apps start`:
```bash
# Terminal 1: start the app preview
stripe apps start
# Terminal 2: start your backend server
node server.js
```
For webhook forwarding during local development, see `references/webhooks.md`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |