> For the complete documentation index, see [llms.txt](https://docs.flora.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flora.ai/mcp/authentication.md). # FLORA MCP authentication How FLORA MCP signs you in with OAuth or a FLORA API key, how agents pick the workspace to bill, and how to disconnect a client or revoke a key. [FLORA MCP](https://flora.ai/mcp) signs you in with your FLORA account over OAuth, so you never paste a key into Claude, ChatGPT or Cursor. For headless setups such as CI jobs and scripts, it also accepts a FLORA API key in the `Authorization` header. | | OAuth (default) | API key | | --------------- | ------------------------------------------- | ------------------------------------------------------------------ | | Use for | Chat and coding clients a person uses | CI, scripts, servers, clients that can't open a browser | | How it connects | Your client opens FLORA's sign-in page once | `Authorization: Bearer ` on every request | | Acts as | You, in every workspace you belong to | You, in the workspaces and with the permissions chosen for the key | | Stored by | Your client | You (environment variable or secrets manager) | | Turn it off | Remove FLORA in the client | Revoke the key in FLORA, and remove it from the client | ## Who can connect API and MCP are included from Starter up. A Free account can also connect and try FLORA MCP on the $2.50 of usage every new workspace gets. What you can do depends on the workspace you pick: * **Starter, Pro, Max and Enterprise** workspaces include API and MCP access. Generations spend the workspace's usage in US dollars. See [How FLORA pricing works](/plans-and-billing/pricing.md). * **Free** workspaces can connect, read and generate. Generations spend the **$2.50** of usage every new workspace gets, the same as in the app; there's no separate MCP trial. Reading is free. When that usage is spent, generations stop with a billing error (`insufficient_credits` or `BILLING_*`). Ongoing use needs Starter or above. * `paid_plan_required` (HTTP 403) means the workspace's plan doesn't include what was asked for, such as API access or another feature. Adding balance doesn't fix it. Pick a workspace whose plan includes it, or ask your FLORA admin about upgrading. ## How sign-in works FLORA MCP is a hosted server at `agents.flora.ai`. Your client sends tool calls to it over HTTPS. Web clients such as Claude and ChatGPT connect from their own servers, not from your computer. 1. Your client calls `https://agents.flora.ai/mcp` without a token and gets `401 Unauthorized`. The `WWW-Authenticate` header points to `https://agents.flora.ai/.well-known/oauth-protected-resource/mcp`. This 401 is normal: it's how clients discover sign-in. 2. The client registers itself with FLORA automatically (dynamic client registration). You don't need a client ID or secret; leave any OAuth fields in your client empty. 3. Your browser opens FLORA's sign-in page on `clerk.flora.ai`. Sign in with the account you use at [app.flora.ai](https://app.flora.ai). If you're already signed in to FLORA in that browser, this step can be quick. 4. FLORA asks for your basic profile and email, plus offline access so your client can stay signed in. 5. The browser hands you back to your client, which stores the tokens and refreshes them as needed. You sign in again only if the refresh fails or you disconnect. There's no workspace picker at sign-in. One connection reaches every workspace your account belongs to (see [Workspaces](#workspaces-chosen-per-call)). For client developers, the OAuth endpoints are: | Endpoint | URL | | ----------------------------- | ------------------------------------------------------------------ | | Protected resource metadata | `https://agents.flora.ai/.well-known/oauth-protected-resource/mcp` | | Authorization server metadata | `https://agents.flora.ai/.well-known/oauth-authorization-server` | | Authorize | `https://agents.flora.ai/authorize` | | Token (also token revocation) | `https://agents.flora.ai/token` | | Dynamic client registration | `https://agents.flora.ai/register` | FLORA supports the authorization code grant with PKCE (`S256`) and refresh tokens. ## What the connection can do The connection acts as you. It can do what your FLORA role allows in each workspace, and nothing more: * Read workspaces, projects, canvases, models, Techniques, assets and run history. * Create projects, add and change nodes, upload assets, and share projects, where your role allows it. * Start generations and Technique runs, which spend the workspace's balance in US dollars. * Read balance and spend with `flora_get_usage` (spend totals need billing permission). No tool manages plans, payment methods or workspace members. Do that in the FLORA app. ## Workspaces: chosen per call A connection isn't scoped to one workspace. Tools take `workspace_id` on each call, and tools that work on a project use that project's own workspace (from `project_id`). If you pass both and they don't match, the call is rejected. One exception: `flora_run_technique` takes no `workspace_id` and bills the connection's [default workspace](/mcp/cost-and-limits.md#default-workspace). See [Run your team's Technique](/mcp/recipes/run-a-technique.md#where-it-bills-and-where-the-outputs-go). `flora_list_workspaces` returns every workspace you can use, with `current_workspace_id` when you're already working in one: ```json { "workspaces": [ { "workspace_id": "ws_123", "name": "Brand Studio", "role": "admin", "organization_id": "org_456", "organization_name": "Acme Inc", "created_at": 1767225600000 }, { "workspace_id": "ws_789", "name": "Client work", "role": "editor", "organization_id": "org_456", "organization_name": "Acme Inc", "created_at": 1759276800000 } ] } ``` **Ask which workspace to bill.** Workspaces differ in plan, balance and model access. When the agent needs a workspace for a new project or generation: * If `current_workspace_id` is present, it uses that one. * If you have one workspace, it uses that one. * If several come back and none is current, it names them and asks you which to bill. It doesn't guess. You can always tell it up front: "Use my Client work workspace." ## API keys for headless setups Use an API key when no person is there to sign in through a browser. FLORA MCP accepts any FLORA API key (keys start with `ak_`; older `flora_sk_` keys also work) as a bearer token: ```http Authorization: Bearer ak_XXXX ``` ### Create a key 1. Sign in to [FLORA](https://app.flora.ai) and open **Settings → API Keys**. In an organization, open **Settings**, choose the workspace under **Workspaces**, and find **API Keys** under **Security**. 2. Click **Create API Key** and name it. 3. Choose the workspaces it can reach and its permissions in each: **Read**, **Write** (needed to generate, upload and edit canvases) and **Billing** (needed for `flora_get_usage`). 4. Copy the key from the **API Key Created** dialog. It isn't shown again. You can hold up to five active keys. Admins can always create keys. Editors can too, unless an admin turns off **Allow editors to create API keys** in the workspace's settings. Full details: [API authentication](/api/platform/authentication.md). ### Add the key to your client Claude Code: ```bash claude mcp add --transport http flora https://agents.flora.ai/mcp \ --header "Authorization: Bearer $FLORA_API_KEY" ``` A JSON config that supports headers: ```json { "mcpServers": { "flora": { "type": "http", "url": "https://agents.flora.ai/mcp", "headers": { "Authorization": "Bearer ${FLORA_API_KEY}" } } } } ``` Keep the key out of anything you commit. Check how your client expands environment variables before you rely on `${...}`. ## Disconnect and revoke Removing FLORA from your client deletes the tokens it stored for FLORA. Do it in each client you connected: | Client | How to disconnect | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Claude (web and Desktop) | See [Claude: Remove](/mcp/install/claude.md#remove) | | Claude Code | `claude mcp remove flora`, or uninstall the plugin (its server is `plugin:flora-mcp-skills:flora`). See [Claude Code: Remove](/mcp/install/claude-code.md#remove) | | ChatGPT | See [ChatGPT: Disconnect](/mcp/install/chatgpt.md#disconnect) | | Codex | `codex mcp logout flora`, then `codex mcp remove flora` | | Cursor | See [Cursor: Remove](/mcp/install/cursor.md#remove) | | VS Code | See [VS Code: Remove](/mcp/install/vscode.md#remove) | | Clients using `mcp-remote` | Remove the server from the config, then delete `~/.mcp-auth` | **Revoke an API key:** in FLORA, open **API Keys**, click **Revoke** next to the key, and confirm. Anything using it loses access right away. Revoking can't be undone. FLORA doesn't list OAuth connections in its settings. If a device with a connected client is lost or shared, remove FLORA from that client if you can, revoke any API keys it used, and email . ## Admin controls Admins control agent access through the same settings that govern the FLORA app: | Control | Where | Effect on MCP | | ------------------------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | Plan | **Plans & Billing** | API and MCP access follow the workspace's plan. Without it, tools return `paid_plan_required`. | | Roles | **Members & Roles** or **People & Seats** | An agent can do only what its user's role allows. | | **Allow editors to create API keys** | Workspace settings, **API key access** | Off: only admins can create keys for the workspace. | | Model access | Workspace settings, **Model access** | Models an admin turns off are left out of `flora_list_models`. | | Spending limits | Member and workspace limits | Agent generations count against them. When one is hit, generation returns a `BILLING_*` error and the agent stops. | On Claude Team and Enterprise, an owner also decides which connectors members can add. See [Install in Claude](/mcp/install/claude.md). ## Related * [Cost, balance and limits](/mcp/cost-and-limits.md) * [Security and data](/mcp/security.md) * [Troubleshooting](/mcp/troubleshooting.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.flora.ai/mcp/authentication.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.