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.

​
What API keys do

API keys authenticate platform API requests and protected MCP endpoint traffic. The target URL determines which access path Horizon evaluates.

Manage Horizon

Send the key to the REST API to list, create, update, or delete resources that the owning actor is allowed to manage.

Call protected servers

Send the key to a Horizon-served MCP endpoint when the client cannot sign in interactively.
API keys are useful for automation because they can be replaced without changing the owner’s sign-in session. They are not a substitute for access control. If the owner loses organization membership, server access, or a needed role permission, requests made with the key lose that access too.

​
Key types

Use personal API keys for work tied to one human user. Use service-account keys for shared automation that should survive user turnover.
Key ownerCreate fromBest forAccess behavior
UserUser menu, then API KeysPersonal scripts, local MCP clients, one-off testingInherits the user’s current organization and server access.
Service accountOrganization settings, then Service AccountsCI/CD, Terraform, scheduled jobs, production integrationsInherits the service account’s organization role and server grants.
For production automation, prefer service accounts. A service account makes ownership explicit and avoids depending on a person’s membership or personal key lifecycle.

​
Create a personal API key

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.

​
Send a request

Send API keys in the Authorization header: 
Authorization: Bearer fmcp_...
For REST API requests: 
curl https://horizon.prefect.io/api/v0/me \
  -H "Authorization: Bearer $HORIZON_API_KEY"
For protected MCP endpoint traffic, configure the client to send the same bearer header to the Horizon deployment URL.
Do not put API keys in source control, client-side application code, shell history, issue text, or screenshots. Treat an exposed key as compromised and rotate it.

​
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.
The key keeps existing as a credential, but requests are evaluated with the owner’s current access. If the owner no longer belongs to the organization or lacks server access, protected requests fail.
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.

​
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.