Skip to main content
External authentication is available on Developer and Enterprise.
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 the configured authentication headers 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

An API-key auth source can send up to ten headers. Configure each header name, its value, and an optional encrypted credential in one editor. This supports providers that require an API key with an organization, tenant, or profile identifier. A header value can contain zero or one {token} placeholder: New headers default to {token} because a provider can treat an identifier as sensitive even when it is not called a secret. Use a literal value only when users who can view the auth configuration can also view that value. Horizon never displays an encrypted credential after it is saved. For example, a provider can require two independent protected values:
Another provider can use an encrypted key with a visible identifier:
Use header injection for remote credentials. Query-string credentials are not a supported authentication channel. A secret embedded in a connector URL can appear anywhere that URL is displayed or recorded. With a per-user API key, each {token} value entered during setup belongs to the current user. Each additional user enters their own values for these headers. Literal values are part of the auth source configuration and apply to every user. With a shared API key, a server administrator saves one credential set for the organization.

​
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

For OAuth, review the discovered registration or enter a pre-registered client. For an API key, add every required header and enter each encrypted value in the same form. Horizon requires every token-backed value before it creates an external server.
4

Authorize OAuth

If you selected OAuth, complete Authorize with OAuth.
5

Create the connector

Review the remote endpoint and authentication mode, then select Create Connector. For a per-user or shared key, Horizon saves the credential values when connector creation succeeds. Horizon sends anonymous requests when you selected no authentication.
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 every downstream header 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 all API-key headers and available credential values. Select Link auth source to save the configuration, attach it to the hosted server, and save the values you entered.
4

Add missing credentials

If you omitted credential values, select Authorize for OAuth, Add token for a per-user key, or Add key for a shared key. OAuth and per-user credentials belong to your signed-in Horizon user. Shared credentials belong 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 headers and that its upstream call succeeds.
To correct a misconfigured OAuth source, open its action menu and select Edit Configuration instead of relinking. The dialog updates the authorization and token endpoints, the issuer, the requested scopes, and how the downstream token is sent. Stored OAuth client settings stay hidden and unchanged unless you select Replace OAuth client. When you replace the client, enter its client ID, token endpoint authentication method, and a new client secret for HTTP Basic or request body authentication. Horizon replaces these settings together so they match the client registered with the provider. It does not use a client secret for no client authentication. Because saved tokens may no longer be valid for the new configuration, Horizon discards them: every user authorizes again after the update, and the change reaches serving configuration without a rebuild. 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 credentials to save personal header values. 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 credentials, 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-key header values 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.