> ## Documentation Index > Fetch the complete documentation index at: https://docs.horizon.prefect.io/llms.txt > Use this file to discover all available pages before exploring further. # Authorization > How Horizon enforces access in the request path: the authorization decision flow, capability filtering, and where role checks run for management and MCP traffic. export const toolAccessPlans = "Enterprise"; export const serverRolesPlans = "Enterprise"; Horizon provides a shared access layer for the servers your organization deploys and the platform resources your team manages. After authentication identifies a caller, Horizon uses the same organization membership, server roles, custom roles, and capability policies to decide what that caller can see, manage, or invoke. This moves access policy out of individual server implementations and into the platform path. Security and platform teams can make servers broadly discoverable, restrict sensitive deployments to specific people, Teams, or service accounts, and expose only the MCP capabilities each role should use. Authorization in Horizon has two related paths: | Path | Actor | Target | Main question | | ----------------- | ------------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------- | | Using MCP servers | An MCP client, agent, or automation calling a server endpoint | A hosted, remix, or external MCP server served through Horizon | Can this actor use this server and requested MCP capability? | | Managing Horizon | A user, script, CI job, service account, or Terraform run | The Horizon dashboard or REST API | Can this actor view or change this organization, server, member, key, or setting? | The same Horizon identity can appear in both paths, but the requested action is different. Calling a Horizon-served MCP endpoint lets a client use tools, resources, and prompts exposed by that server. Managing Horizon lets a user or service account change servers, members, API keys, builds, access settings, and organization settings. Authentication is separate. Authentication answers "who is calling?" Authorization answers "what is this caller allowed to do?" For the identity and credential path, see [Authentication](/platform/authentication). Horizon evaluates authorization at three levels: Determines whether the actor belongs to the organization and whether they can manage organization-wide settings such as members, billing contact assignment, SSO, service accounts, and server roles. Determines whether the actor can discover, call, view, edit, deploy, or administer a specific server. Determines which MCP tools, resources, and prompts are available to the actor's resolved server roles. Custom server roles and team server grants are available on {serverRolesPlans}. Tool-level access is available on {toolAccessPlans}. ## Request decision flow When a protected MCP request reaches Horizon, the gateway checks access before the request reaches server code. Horizon authenticates the bearer credential and resolves it to a user or service account. Invalid, expired, revoked, or missing credentials fail before authorization. The actor must belong to the organization that owns the server. An actor in another organization cannot use that organization's servers. Horizon resolves the actor's server role set from organization privileges, explicit server grants, Team grants, and the server's default role. If the server has tool-level access configured, Horizon allows tools, resources, and prompts whose policy permits at least one resolved role. Allowed requests continue to the server. Denied requests stop at the gateway. Disabling Horizon authentication removes Horizon gateway authentication and server access checks for that hosted server endpoint. Do so only when the endpoint is intentionally public or the server implements its own authentication and authorization. This is available only for hosted servers; remix servers and external servers always keep Horizon authentication enabled. ## Roles and actors Authorization resolves against an **actor** (a user or service account) using that actor's organization role, explicit server grants, Team grants for users, and the server's default role. API keys inherit access from the actor that owns them, so revoking a key disables that credential without changing the owner's roles. [Roles](/roles) is the canonical reference for the role model: the built-in organization roles (`admin`, `member`), the built-in server roles (`admin`, `editor`, `viewer`), custom server roles, default roles, explicit grants, and team grants. This page covers where those roles are enforced in the request path rather than redefining them. Server roles are not hierarchical in capability policies. If both `viewer` and `editor` should access a capability, both roles must be allowed. Use `*` only when every server role should have access. ## Capability-level access Capability-level access controls which MCP tools, resources, and prompts are available to each server role. When an actor holds multiple roles, a capability is available if its policy allows at least one of them. Capability access is configured from a server's Settings pages after Horizon has a manifest for the server. For hosted servers, saved capability policy changes apply to the dashboard immediately, but live MCP endpoint traffic uses the updated policy after the next deployment. Explicit grant, team grant, and server default role changes do not require a code change or rebuild. Capability access has two layers: | Layer | What it controls | | -------------------- | ------------------------------------------------------------------- | | Default permissions | Which roles can access tools, resources, and prompts by default. | | Capability overrides | Per-tool, per-resource, and per-prompt exceptions from the default. | When no capability policy is configured, the server's capabilities are not filtered by tool-level access. After a capability policy is configured, any tool, resource, or prompt without a matching default or override is denied. Per-capability overrides can: | Override | Effect | | ----------------- | ---------------------------------------------------- | | Default | Inherit the server's default capability permissions. | | All roles | Allow every server role. | | One or more roles | Allow only the listed roles. | Horizon keeps the `admin` server role allowed in capability policies. Organization admins and server admins can recover access to server capabilities. Capability policies apply to MCP tools, MCP resources, resource templates, and MCP prompts. Resource templates use the resource access settings. ## Applying changes Authorization changes have different lifecycle boundaries depending on what you change. | Change | When it affects Horizon management | When it affects MCP endpoint traffic | | --------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | Organization role change | On the next authenticated dashboard or API request. | On the next authenticated MCP request that resolves the actor's current access. | | Explicit server grant change | After the change is saved. | After Horizon updates the live deployment's access metadata. No code change is required. | | Team server grant change | After the change is saved. | After Horizon updates the live deployment's access metadata. No code change is required. | | Directory-backed Team membership change | After Directory Sync processes the membership. | After Horizon updates the live deployment's access metadata. No code change is required. | | Server default role change | After the change is saved. | After Horizon updates the live deployment's access metadata. No code change is required. | | Capability policy change | After the change is saved in Horizon. | For hosted servers, after redeploying the server so the deployed endpoint uses the updated policy. | | API key revocation | Immediately stops that key from authenticating. | Immediately stops that key from authenticating. | For hosted servers, if you save default capability permissions or a capability override, redeploy the server before expecting MCP clients to see the new tool, resource, or prompt availability. ## Common outcomes Horizon authenticated the actor, found organization membership, resolved one or more server roles, and allowed the requested server or capability. Authentication failed before authorization. Check the bearer credential, API key state, token expiration, and target organization. Authentication succeeded, but authorization denied access to the organization, server, or requested capability. Check the actor's organization role, explicit and team server grants, the server default role, and capability policy. The server or deployment does not exist, or Horizon is concealing a server from a caller without discovery access. The actor may have server access but not capability access. Check the server's default capability permissions and any per-capability overrides, then redeploy hosted servers if the policy was changed. ## Operational guidance For production servers, keep Horizon authentication enabled and use server roles to control who can manage or call it. Prefer service accounts with narrowly scoped server grants for automation. Use `No Access` as the default role for sensitive servers, then grant access to the people, Teams, and service accounts that need it. Use a `Viewer` default for broadly discoverable servers where most members should be able to inspect or call safe capabilities. Use capability-level access for high-impact tools, sensitive resources, and prompts that should not be available to every server user. Keep destructive or write-capable tools restricted to roles that are meant to perform those actions. ## Related docs The canonical reference for organization roles, server roles, custom roles, default roles, explicit grants, and team grants. Learn how users, service accounts, MCP clients, and API keys prove identity. Learn where authentication and authorization run in the request path. Invite, remove, and manage people in your organization. Create, rotate, and revoke bearer credentials. Review product limits that can affect server requests.