skills/stripe-apps/references/backend.md

# 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 backend code, read these pages using WebFetch:

| 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 will not 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`.