An agent acts with the API key you give it, so the key is the boundary: give each agent its own key with only the access its job needs, and let the account's own controls (approval limits, the activity log, read-only money movement) do the rest. Everything below applies the same to the MCP server and to the REST API.
What an agent can never do
- Move money out of your balance: payouts and the balance can only be read, by any key. Payouts are made in the dashboard by owners and admins.
- Refund past your approval limit: a refund over it waits for an owner (below).
- Respond to disputes, change your settings, team or keys, or create other keys.
- Act after you revoke its key: revoking takes effect on the next request.
Presets per use case
In Settings → Developers → Create key, choose Read only, or Custom and set each resource to none, read or write as below (write includes read). A key's access is fixed when it's made: for different access, make a new key and revoke the old one.
| Use case | Job | Key access | MCP tools it can use |
|---|---|---|---|
| Bookkeeping and reporting | Answers questions about sales, refunds, payouts and disputes; reconciles a month. | Read only | list_payments, get_payment, list_payment_links, get_payment_link, list_invoices, get_invoice, list_customers, get_customer, list_refunds, get_refund, list_products, get_product, list_subscription_plans, get_subscription_plan, list_subscriptions, get_subscription, list_discount_codes, get_discount_code, list_payouts, get_payout, get_balance, list_disputes, get_dispute, list_webhook_endpoints, get_webhook_endpoint, list_events, get_event |
| Invoicing assistant | Drafts, sends and chases invoices; adds the customers it invoices. | invoices write, customers write, payments read | list_payments, get_payment, list_invoices, create_invoice, get_invoice, send_invoice, list_customers, create_customer, get_customer, update_customer |
| Sales assistant | Makes payment links and discount codes for deals, and checks who paid. | payment_links write, discount_codes write, products read, payments read | list_payments, get_payment, list_payment_links, create_payment_link, get_payment_link, update_payment_link, deactivate_payment_link, list_products, get_product, list_discount_codes, create_discount_code, get_discount_code, deactivate_discount_code |
| Customer support | Looks up a customer's payments and subscription, refunds within your approval limit, cancels or pauses on request. | payments read, refunds write, customers read, subscriptions write, disputes read | list_payments, get_payment, list_customers, get_customer, list_refunds, get_refund, create_refund, list_subscription_plans, create_subscription_plan, get_subscription_plan, list_subscriptions, get_subscription, cancel_subscription, pause_subscription, resume_subscription, list_disputes, get_dispute |
| Catalog upkeep | Keeps products and prices in step with your inventory. | products write | list_products, create_product, get_product, update_product, archive_product |
| Developer assistant | Writes and tests your integration's code; sets up its webhook endpoint. | webhook_endpoints write, payment_links read, payments read | list_payments, get_payment, list_payment_links, get_payment_link, list_webhook_endpoints, create_webhook_endpoint, get_webhook_endpoint, update_webhook_endpoint, delete_webhook_endpoint, send_test_event |
Resources a key can be given: payments (Payments), refunds (Refunds), payment_links (Payment links), invoices (Invoices), customers (Customers), products (Products), subscriptions (Subscriptions), discount_codes (Discount codes), payouts (Payouts), disputes (Disputes), webhook_endpoints (Webhook endpoints), events (Events). The full list of what each one allows is on Authentication.
Approval limits for refunds
An API key refunds like an admin. Set a refund approval limit in Settings → Team & approvals and any refund over it, by an admin, a key or an agent, waits for an owner: the agent gets status: "pending_approval" and nothing is refunded until an owner approves it in the dashboard. Set the limit to $0 and every refund an agent makes waits for you (admins' refunds too).
Keep a person in the loop
- Tools that change data are marked
readOnlyHint: false; refunds, cancellations, archiving, deactivating and deleting are alsodestructiveHint: true, and tools that email customers areopenWorldHint: true. Clients that ask before acting, such as Claude, use these: keep those confirmations on for keys that can write. - Ask agents to draft first:
create_invoicewithsend: falsemakes the invoice without emailing it, so you can review it and send it withsend_invoice. - Every change an agent makes is in your activity log under its key's name.
Retries never act twice
Agents retry. Every tool that changes something takes an idempotencyKey argument, sent as the Idempotency-Key header: the same key within 24 hours returns the first result instead of acting again. Tell your agent to make one per action (“use refund-order-1042 as the idempotency key”).
Untrusted text
Customer names, invoice notes, checkout answers and metadata are written by other people. An agent that reads them can meet text that looks like instructions. Give agents that read customer data a Read only key unless they truly need to write, and keep confirmations on for every write.
Checklist
- One key per agent, named after it, with the smallest preset that does the job.
- A refund approval limit, if the agent can refund.
- The key in the client's secret store or an environment variable, never in a shared file or a chat.
- Confirmations on in the client for tools that change data.
- Review the activity log; revoke the key the day the agent is retired.