Security best practices - Flex Documentation

Understand the scope of each auth mode

If you don’t need write access, don’t grant it. The most common misuse pattern is connecting a fully-privileged credential to an assistant that only needs to look things up.

Use scoped API keys

When you create an API key in the Flex Dashboard, you can restrict it to specific resources and actions using the resource:read / resource:write scope model. Scopes available include:

• products:read / products:write
• prices:read / prices:write
• customers:read / customers:write
• checkout_sessions:read / checkout_sessions:write
• payment_intents:read / payment_intents:write
• refunds:read / refunds:write
• And more for coupons, captures, promo codes, and other resources.

For an assistant that’s primarily used for support lookups and analytics, a key with only *:read scopes is much safer than a full-access key — Claude can answer questions but can’t create products, issue refunds, or mutate customer records even if it wanted to.

OAuth doesn’t currently support sub-scoping below the signed-in user’s permissions. If you need scope-limited access for an AI assistant, use the API key path.

Default to test mode

Always start in test mode. With API keys this is automatic — use a key with the fsk_test_ prefix. With OAuth, instruct your assistant up front:

Use test mode (api_test_mode: true) for every Flex tool call in this conversation.

Only switch to live data once you’ve verified the assistant uses the right tools in the right way for your specific workflows. See Test mode for the full mechanics.

Rotate keys

Treat MCP API keys like any other backend credential:

• Don’t commit them to source control.
• Don’t paste them into shared chats or screenshare them.
• Rotate them when a team member leaves, when a device is lost, or on a regular cadence aligned with your security policy.
• Revoke unused keys from the API keys page.

If you suspect a key has been exposed, revoke it immediately from the Dashboard. The key will stop working on the next request.

Review tool-use approvals

Both Claude.ai and Claude Code surface a prompt the first time a Flex tool is called in a conversation. Read what it’s asking before clicking “Allow for all tasks” — that approval persists for the rest of the conversation. For destructive operations (refunds, product mutations, subscription changes), prefer “Allow once” so each call gets an explicit greenlight.

Audit access

Every MCP request is authenticated and logged the same way as direct Flex API requests. If you suspect misuse, contact Flex support and we can help trace activity tied to the credential.