Skip to main content
API keys are bearer credentials for non-interactive access to Horizon. Use them when a script, CI job, Terraform run, service account, or MCP client needs to authenticate without completing an interactive sign-in flow. An API key proves the identity of the actor that owns it. That owner can be a user or a service account. The key does not carry a separate permission scope: Horizon evaluates the owner’s current organization role, server access, and capability access on each request.
Horizon API keys start with fmcp_. The full key is shown only once, when you create it. Store it before closing the creation dialog.

​
Key types

Choose the owner based on who should appear as the actor and how long the workflow should outlive a person.
For production automation, prefer service accounts. A service account makes ownership explicit and avoids depending on a person’s membership or personal key lifecycle.

​
Permissions

A key can perform only the actions its owner can perform. For the REST API, organization and server permissions control which resources the actor can read or change. For an MCP endpoint, organization membership, server access, and capability policies control which tools, resources, and prompts the actor can use. Keys do not elevate access or preserve permissions that their owner has lost. See Roles for the organization and server role contracts, and Authorization for how Horizon resolves them on each request.

​
Supported surfaces

Both key types use the same header on the two customer-facing surfaces that accept Horizon API keys:
The target URL decides whether Horizon applies management permissions or MCP server access.

​
REST API

The Horizon REST API accepts personal and service-account keys. Each operation checks whether the owning actor has the required access. Use the interactive API reference for the current routes, request schemas, and response schemas. This request lists the organizations available to the key owner. For a one-off test, read the key without saving it in shell history. In automation, load the same environment variable from your secret manager.

​
MCP endpoints

A protected hosted, external, or remix server accepts a Horizon API key at its serving URL. The gateway resolves the key owner, checks organization and server access, applies capability permissions, and then forwards an accepted MCP request. Use the stable /mcp URL from the server’s Connect page. This example sends an MCP initialize request directly. Most users configure the same URL and header in an MCP client instead.

​
Credential boundaries

A Horizon API key authenticates only at a Horizon API or gateway boundary. Adjacent surfaces use different credentials.
A service-account key can authenticate to a protected hosted server, but per-actor delegated authorization is not supported for service accounts. Browser authorization saves the downstream credential for the signed-in user, not the service account. Automation must provide its upstream credential through the hosted server, such as with an environment variable, until service-account delegated authorization is supported.

​
Personal keys

Create a personal API key for work that should act as your user identity.
1

Open API Keys

In Horizon, open the user menu and select API Keys.
2

Create the key

Select Create API Key. Add a descriptor that identifies where the key will be used, such as local-client or staging-ci.
3

Store the secret

Copy the fmcp_ value from the reveal dialog and store it in the client, CI secret store, or secret manager that will send requests.
4

Grant server access

Confirm the user has access to every organization and server the key needs. The key cannot exceed the user’s current access.

​
Create a service-account API key

Create service-account keys from an organization’s service account settings. Service accounts are designed for automation, so their keys can be rotated without involving a human user’s account.
1

Open Service Accounts

Go to organization settings and select Service Accounts.
2

Create or select a service account

Create a new service account for the automation, or open an existing service account that already owns the right access.
3

Copy the generated key

New service accounts receive an API key when created. Existing service accounts can have additional keys added from the service account details panel.
4

Assign access

Give the service account the organization role, explicit server grants, and capability access it needs.
Service accounts can have up to two active API keys at a time. This supports zero-downtime rotation: add a replacement key, move traffic, then revoke the old key.

​
Rotation workflow

Rotate keys by introducing a replacement before revoking the old key.
1

Create a replacement key

Create a new key for the same user or service account. For service accounts, keep the two-key limit in mind.
2

Update the client

Change the secret value used by the MCP client, CI job, Terraform run, or integration.
3

Verify new traffic

Confirm the client succeeds with the new key. Check request logs or the client response before removing the old key.
4

Revoke the old key

Delete or revoke the old key. Revocation stops that key from authenticating immediately.

​
Lifecycle and access

API key behavior follows the owner and the active key record.
Removing the member deletes their membership and explicit server grants in that organization. Their personal API key remains active, but it loses access to the organization they left. The same key can still access other organizations where the user remains a member.Move shared automation to a service account before offboarding the user. Reinviting the user later does not restore their previous explicit server grants.
Horizon stops accepting the key immediately. Existing clients must be updated to use another key or sign-in method.
Horizon cannot show the full key again. Create a new key, update the client, and revoke the old key if it might still be in use.
Requests made with that service account’s keys can no longer use the suspended or deleted identity. Replace the key with one owned by an active service account that has the required access.

​
Security

Store keys in a secret manager or the encrypted secret store provided by your CI system. Keep them out of source control, client-side application code, shell history, issue text, screenshots, logs, and traces. Treat an exposed key as compromised and rotate it. Give each key a descriptor that identifies its integration, and use a separate key per integration so each credential can be rotated without disrupting unrelated clients. Keys owned by the same actor still share one identity and permission set. For least privilege and clearer audit attribution, create a separate service account for each production workflow and grant only the access it needs. Request logs and usage views attribute protected MCP traffic to the user or service account that owns the key. They do not distinguish between multiple keys owned by that same actor, and they never display the raw key. Use separate service accounts when audit records must distinguish one automation from another.

​
Common failures

Horizon did not accept the credential. Check that the request uses Authorization: Bearer, that the key starts with fmcp_, that the full value was copied, and that the key has not been revoked.
The key authenticated, but the owning actor does not have permission for the organization, server, or action. Check the owner’s organization role, server grants, default server role, and capability policy.
The deployment URL may not map to a live server, or Horizon may be concealing a server from an authenticated actor that lacks discovery access. Confirm the URL and the owner’s server access.
Revoke an unused service-account key first. Service accounts support up to two active keys at a time.

Authentication

Learn how API keys, user tokens, and browser sessions authenticate.

Authorization

Learn how Horizon decides what an authenticated actor can do.