Overview
Set up a Stripe restricted API key so the assistant can interact with a Stripe account — querying customers, managing subscriptions, processing refunds, reading invoices, and monitoring payments as a scoped entity.
Restricted API keys (RAKs) limit access to only the specific Stripe resources the assistant needs, reducing the blast radius if a key is ever compromised. RAKs are drop-in replacements for secret keys — they work identically with every Stripe API.
Total manual effort: ~2 interactions — create the restricted key in the Dashboard and hand it over via secure prompt.
Prerequisites
- User must have admin or developer access to the Stripe account
- User must be logged into the Stripe Dashboard in their browser
Setup Flow
Step 0: Check Existing Configuration
Before starting, check whether Stripe is already configured by running the check script:
bashbun skills/stripe-app-setup/scripts/check-config.ts
The script outputs JSON: { "configured": boolean, "details": string }.
- If
configuredistrue— Stripe is already set up. Offer to verify the connection or reconfigure. - If
configuredisfalse— continue to Step 1.
Step 1: Create the Restricted API Key
Direct the user to create a new restricted key:
Open https://dashboard.stripe.com/apikeys and click + Create restricted key.
When Stripe asks "How will you use this API key?", select Providing this key to another website and enter the assistant's name.
Guide them through the permissions. A good default for managing payments, customers, and subscriptions:
| Resource | Access Level |
|---|---|
| Customers | Read & Write |
| Charges | Read & Write |
| Invoices | Read & Write |
| Payment Intents | Read & Write |
| Subscriptions | Read & Write |
| Products | Read |
| Prices | Read |
| Balance | Read |
| Disputes | Read |
| Payouts | Read |
Adjust permissions up or down based on the user's needs. The principle of least privilege applies — only request what the assistant will actually use. For read-only monitoring, set everything to Read.
Click Create key when done.
Important: The restricted key is revealed only once after creation. The user must copy it immediately.
Step 2: Collect the API Key
After the user copies their restricted key, run the store script to securely collect and store it:
bashbun skills/stripe-app-setup/scripts/store-key.ts
The script opens a secure credential prompt in the user's app, stores the key in the encrypted vault with the correct injection templates for api.stripe.com, and exits. If it exits 0, the key is stored. Exit code 130 means the user cancelled the prompt — nothing was stored; that's a valid choice, not an error, so ask whether they'd like to try again rather than treating it as a failure. Any other non-zero exit is a real failure.
Step 3: Verify
After storing the key, verify the connection:
bashcurl -s https://api.stripe.com/v1/balance
Run with network_mode: "proxied" and the stripe credential. A successful response returns the account's balance object with available and pending arrays.
If the response returns a 401, the key is invalid or revoked. If 403, the key doesn't have the required permissions for the endpoint.
Step 4: Report Success
Summarize with the completed checklist:
"Setup complete! ✅ Restricted API key configured ✅ Connection verified — balance accessible
Key type: Restricted API key (rk_...)
Permissions: {list the configured permission levels}
Key management: https://dashboard.stripe.com/apikeys"
API Usage
After setup, use bash with curl to call the Stripe API. The credential proxy injects the Authorization: Bearer header automatically when using network_mode: "proxied" with the stripe credential.
Common API Calls
List customers:
bashcurl -s https://api.stripe.com/v1/customers?limit=10
Create a customer:
bashcurl -s https://api.stripe.com/v1/customers \ -d "email=customer@example.com" \ -d "name=Jane Doe"
List recent payments:
bashcurl -s https://api.stripe.com/v1/payment_intents?limit=10
List subscriptions:
bashcurl -s https://api.stripe.com/v1/subscriptions?limit=10
Retrieve an invoice:
bashcurl -s https://api.stripe.com/v1/invoices/{invoice_id}
Issue a refund:
bashcurl -s https://api.stripe.com/v1/refunds \ -d "payment_intent={pi_id}"
All calls use network_mode: "proxied" with the stripe credential.
Pagination
Stripe uses cursor-based pagination. Use starting_after with the last object's ID to page forward:
bashcurl -s "https://api.stripe.com/v1/customers?limit=100&starting_after=cus_lastId"
Sandbox vs Live
Stripe has separate sandbox and live modes with separate API keys. Keys starting with rk_test_ are sandbox keys; rk_live_ are live keys. The assistant uses whichever key the user provides.
Credential Reference
All credentials are stored under service: stripe:
| Field | Description | When Set |
|---|---|---|
api_key | Restricted API key (rk_live_ or rk_test_) | Step 2 |
Troubleshooting
401 Unauthorized
The API key is invalid or has been revoked. Create a new restricted key in the Dashboard and re-run Step 2.
403 Forbidden / "Insufficient permissions"
The restricted key doesn't have the required permission for the API endpoint being called. Edit the key's permissions in the Dashboard at https://dashboard.stripe.com/apikeys (click the overflow menu → Edit key).
"No such customer" / "No such subscription"
Sandbox and live mode are separate environments. A sandbox key can't access live mode objects and vice versa. Confirm the key mode matches the data being queried.
Important Notes
- Restricted API keys do not expire automatically. They remain valid until revoked in the Dashboard.
- Live mode restricted keys can only be revealed once — the user must copy immediately after creation.
- Always confirm with the user before performing write operations (creating charges, issuing refunds, modifying subscriptions).
- Stripe rate limits API calls — standard limit is 100 read operations/second and 100 write operations/second per key.
