Skip to main content
External authentication is available on .
External authentication controls the credential that Horizon sends to a downstream service. The MCP client first proves who the caller is to Horizon. Horizon then sends an OAuth token or API key for that caller, or sends no credential when a remote MCP server accepts anonymous requests. For credential-based modes, an external auth configuration is the saved definition for that second credential. The Horizon dashboard presents it as an auth source. It records how to acquire and inject credentials, while each user’s OAuth grant or API key is stored separately. The no-authentication mode does not create an auth source. Horizon uses external auth configurations in two places: The two credentials serve different trust boundaries: For the first boundary, see Authentication. Server roles and capability policies are covered in Authorization.

​
Authentication modes

Choose the mode based on whether the downstream provider requires a credential and who owns that credential. No authentication applies only to external servers. Horizon still authenticates and authorizes the caller at the Horizon endpoint, but it does not forward the caller’s Horizon credential to the remote MCP server.
Select no authentication only when the remote MCP server accepts anonymous requests. Horizon sends no downstream Authorization header in this mode.
OAuth and per-user API keys preserve the downstream user’s identity and permissions. A shared API key makes every forwarded request act as the same upstream principal, even though Horizon continues to identify and authorize the original caller at its own gateway.
A shared API key gives every authorized caller the downstream permissions of the shared upstream principal. Scope that principal to only the access the server needs.

​
OAuth setup

Horizon starts OAuth setup with the provider or remote MCP URL. It follows protected-resource and authorization-server metadata to locate the OAuth endpoints. When manual setup is required, register Horizon’s callback URL with the provider, then enter the resulting client details in Horizon. For the hosted Horizon control plane, use https://horizon.prefect.io/oauth/external/callback. After the configuration is saved, each user completes the provider flow for their own Horizon identity. External-server users can select Authorize from the server’s Connection page. Hosted-server users authorize when connecting an interactive MCP client, as described in User authorization. Horizon stores the resulting credential for that Horizon actor. The MCP client never receives the provider token.

​
API-key setup

API-key configurations define both who supplies the key and how Horizon places it on the downstream request. The default sends a bearer token in the standard HTTP authorization header: The header value must contain {token}. Horizon replaces that placeholder with the stored key when it forwards a request. This supports raw-key headers as well as providers that require a custom scheme or token format. Use header injection for remote credentials. Query-string credentials are not a supported authentication channel, and a secret embedded in a connector URL can be exposed anywhere that URL is displayed or recorded. A remote MCP server that requires a credential must accept it through an HTTP header. With a per-user API key, the configuration is created without a key. External-server users can select Add token from the server’s Connection page. Hosted-server users add their key through the client authorization flow described in User authorization. With a shared API key, a server administrator selects Add key and saves the organization-wide value. Saved values are not displayed again.

​
External servers

An external server always authenticates the client at the Horizon-served endpoint. Horizon then uses the configured external credential, or no credential for a public remote MCP server, when it forwards the request.
1

Choose a connector

From Servers, start creating an external server. Select a global connector, or add and select an organization connector for the remote MCP endpoint.
2

Choose authentication

Enter the connector name, then select No authentication, OAuth (per user), Key (per user), or Key (shared). Select no authentication only when the remote server accepts anonymous requests.
3

Configure the provider

If authentication is required, review the discovered OAuth registration or open OAuth Configuration and enter a pre-registered client. For an API key, set the header name and header value template expected by the remote server.
4

Add the first credential

If authentication is required, complete Authorize with OAuth, enter your personal API key, or enter the shared key. Horizon verifies that a credential has been saved before continuing.
5

Create the connector

Review the remote endpoint and authentication mode, then select Create Connector. Horizon uses the saved credential when one is configured and sends anonymous requests otherwise.
For OAuth and per-user API keys, every additional user must authorize the remote server separately. They can open the external server’s Connection page to authorize, replace, or revoke their credential. A user who has Horizon server access but no valid remote credential can pass Horizon’s access checks and still receive an authentication failure from the remote server.

​
Delegated authorization

Hosted delegated authorization applies the same external auth configuration to a hosted server. It is useful when hosted server code calls an upstream API as the signed-in user and already expects that provider’s token in an HTTP request header. The setup flow and runtime flow form a double handshake:
  1. The user authorizes Horizon with the upstream provider, or stores a personal token in Horizon.
  2. The MCP client authenticates to Horizon. The trusted gateway identifies the Horizon user, exchanges that identity for the saved downstream credential, and injects the credential before invoking hosted server code.
Setup Runtime On a successful exchange, Horizon removes the inbound Horizon Authorization header. It then injects the downstream credential using the header name and value configured by the auth source. For the default OAuth configuration, hosted server code receives:
Horizon completes the exchange before hosted server code runs and injects only the resulting downstream credential. Your code cannot access the auth source or other credentials stored in Horizon. Code that already reads the configured header can use delegated authorization without implementing its own OAuth callback or credential storage.

​
Configure delegation

Delegated authorization requires Horizon Authentication to remain enabled for the hosted server. Linking and unlinking an auth source updates serving configuration without rebuilding or redeploying the hosted server. The Access and Authentication page requires server write access, so these configuration steps are for a server administrator.
1

Open authentication

Open the hosted server, then select Access and Authentication. Confirm that Horizon Authentication is enabled.
2

Link an auth source

In Delegated authentication, select Link auth source. Give the source a recognizable name and choose OAuth, per-user API key, or shared API key.
3

Configure credentials

Complete OAuth discovery and registration, or configure the API-key header and value template. Select Link auth source to create the configuration and attach it to the hosted server.
4

Add the first credential

Select Authorize, Add token, or Add key beside the linked source. OAuth and per-user API-key credentials belong to your signed-in Horizon user. A shared key belongs to the organization.
5

Test the exchange

Call the hosted server through its Horizon endpoint as an authorized user. Confirm that the hosted handler receives the configured downstream header and that its upstream call succeeds.
To stop delegated exchange, open the linked source’s action menu and select Unlink auth source. Unlinking disables delegated authorization for the hosted server and removes the saved link from serving configuration. Users must authorize again if the source is linked later.

​
User authorization

OAuth and per-user API-key auth sources require every caller to save their own downstream credential. Users with server access do not need server write access to complete this authorization. An interactive MCP client starts the self-authorization flow when it first connects to the hosted server. After Horizon sign-in, the Horizon is requesting access page lists the linked auth source. Select Needs Access to complete OAuth or Needs API key to save a personal token. Horizon then completes the client connection. A client that uses a personal Horizon API key does not open this browser flow. Before connecting that client, sign in to Horizon in a browser and open:
Replace <server-slug> with the hostname prefix from the hosted server URL. For example, the slug in https://weather-mcp.fastmcp.app/mcp is weather-mcp. Authorize the provider or add the personal token, then retry the client. This self-authorization page requires server access, while auth-source configuration remains restricted to server writers. Service-account keys cannot use delegated authorization. Authorizing in the browser saves the downstream credential for the signed-in user, not the service account. Automation that authenticates with a service-account key must provide its upstream credential through the hosted server itself, such as with an environment variable, until service-account delegated authorization is supported. For user actors, a shared downstream API key needs no per-user authorization. Horizon uses the organization-wide credential configured by the server administrator.

​
Current boundaries

Hosted delegated authorization has the following first-version boundaries: Fail-open behavior preserves hosted server availability when a credential is missing, expired, revoked, or temporarily unavailable. It does not bypass the initial Horizon authentication or server access checks, which happen before the exchange. The hosted server will not receive a usable downstream credential, so its upstream call will normally fail authentication unless the server has an independent fallback. Horizon encrypts OAuth client secrets, OAuth tokens, and API keys at rest. It keeps credential material out of normal responses, logs, and traces. For the storage and encryption boundary, see Data protection.

Authentication

Understand how callers authenticate to Horizon before external exchange.

External servers

Register and operate remote MCP servers through the Horizon gateway.

Hosted servers

Build and run MCP servers that can use delegated authorization.

Data protection

Review how Horizon protects credentials and other sensitive values.