Security Best Practices

Financial APIs require strict handling of secrets, webhooks, and idempotency. Follow these practices for every Bags integration.

API keys

• Never expose keys in client-side code — browser bundles, mobile apps, or public repos. Keys belong on your server only.
• Use test keys while building — bag_test_sk_* for sandbox; switch to bag_live_sk_* only after KYB approval.
• Rotate on compromise — revoke the key in Developer Settings and issue a new one immediately.
• One key per environment — separate staging and production keys; never share a live key across teams in chat.

Store keys in environment variables or a secrets manager (Vault, AWS Secrets Manager, Doppler, etc.).

Webhook verification

Every webhook from Bags includes:

Always verify the signature before processing. Reject requests with invalid signatures with 401.

See Handle Webhooks for verification code in TypeScript and Python.

Webhook endpoint hygiene

• HTTPS only — Bags rejects non-HTTPS webhook URLs in production.
• Return 2xx quickly — acknowledge receipt, then process asynchronously (queue the event).
• Idempotent handlers — use sessionId or txHash as dedup keys; Bags may deliver the same event more than once.
• Separate test and live — branch on the livemode field in the payload.

Idempotency

Mutating financial endpoints support idempotency keys where noted in the API reference. Send:

Idempotency-Key: <unique-uuid>

Reusing the same key with the same payload returns the original response instead of double-charging or double-creating resources.

Checkout safety

• Treat webhooks as source of truth — never grant access based solely on client-side wallet confirmation.
• Validate amounts server-side — compare webhook amount against your order record before fulfillment.
• Use tax quote tokens — pass the signed quoteToken from /api/tax/quote into checkout sessions so totals cannot be tampered with.

Agent & MCP usage

The public MCP tools (bags-preview-payment-link, bags-tax-quote) expose read-only public metadata and anonymous tax quotes. They are rate-limited per IP.

Do not expose merchant-scoped data through custom MCP wrappers without authenticating the caller.

Support

• Live Support: Bags Slack community
• Email: hello@getbags.app

What's next