> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withflex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How the Flex MCP authenticates clients, and how to use test mode safely.

The Flex MCP supports two authentication modes. Pick the one that matches your client; both scope access to your partner account and tag every request with the calling identity for audit purposes.

## OAuth

The OAuth path is what most graphical clients use — Claude.ai, Claude Desktop, Cursor, Windsurf, VS Code. The user clicks a button, signs in to Flex through a browser, and approves the connection.

* **Endpoint:** `https://mcp.withflex.com/api/mcp/oauth`
* **Sign-in identity:** Your Flex Dashboard user (the same one you sign in to [dashboard.withflex.com](https://dashboard.withflex.com) with).
* **Scope:** Same access as that user has in the Flex Dashboard, across the partner they belong to.
* **Tokens:** Short-lived; clients refresh transparently. No secrets to copy or paste.

OAuth is the recommended path for any client that can open a browser window.

## API key

The API key path is for headless agents — Claude Code, CI jobs, scripts — where popping a browser is awkward. You generate a key once in the Flex Dashboard and paste it into your client's MCP config as an `Authorization: Bearer` header.

* **Endpoint:** `https://mcp.withflex.com/api/mcp`
* **Header:** `Authorization: Bearer fsk_…` (live) or `Authorization: Bearer fsk_test_…` (test)
* **Generate keys:** [dashboard.withflex.com/apikeys](https://dashboard.withflex.com/apikeys)
* **Scope:** Whatever scopes you assigned the key (e.g. `payment_intents:read`, `refunds:write`). A key with no scopes has full partner access.

Treat MCP API keys exactly like backend API keys: never commit them, never paste them into a shared chat, and rotate them on the same cadence as the rest of your secrets. See [Security best practices](/developer-guides/integration/mcp/security) for recommendations.

## Test mode

Flex separates test data from live data. The two MCP paths handle this differently — important to understand before you connect a production account.

### API key path

The key prefix encodes the mode:

| Prefix       | What it does                                           |
| :----------- | :----------------------------------------------------- |
| `fsk_test_…` | All calls hit test data. Safe for experimentation.     |
| `fsk_…`      | All calls hit live data. Real refunds, real customers. |

The mode is fixed for the lifetime of the key — there's no per-call override. To switch, install a different key. This is atomic and hard to get wrong, which is why we recommend it for Claude Code.

### OAuth path

OAuth tokens don't encode test vs. live, because the same Flex user has access to both. Instead, every tool the MCP exposes takes an `api_test_mode` parameter:

* **Read tools** — Defaults to `false` (live data) if you don't specify. Pass `true` to query test data.
* **Write tools** — The MCP requires you (or the LLM) to set `api_test_mode` explicitly. Mutating live data without saying so is blocked.

When you're getting started, give the assistant a clear instruction up front:

> Use test mode (`api_test_mode: true`) for every Flex tool call in this conversation. Don't touch live data unless I explicitly say so.

Then flip to live only once you're comfortable.

<Warning>
  Until you're confident in how your AI assistant uses the Flex MCP, **work in test mode**. A misinterpreted instruction in live mode can create a real product, issue a real refund, or charge a real customer. Test mode is risk-free.
</Warning>

## Identifying which endpoint to use

| If your client…                                                                        | Use this endpoint                        |
| :------------------------------------------------------------------------------------- | :--------------------------------------- |
| …can open a browser for sign-in (Claude.ai, Claude Desktop, Cursor, Windsurf, VS Code) | `https://mcp.withflex.com/api/mcp/oauth` |
| …is headless or you prefer scoped keys (Claude Code, scripts, CI)                      | `https://mcp.withflex.com/api/mcp`       |

The [Flex MCP landing page](https://mcp.withflex.com) generates the exact install snippet for either path.