> ## 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. # Roles > How organization roles, server roles, custom roles, and capability access decide what people and service accounts can do in Horizon. export const toolAccessPlans = "Enterprise"; export const serverRolesPlans = "Enterprise"; Roles decide what an authenticated actor can do after Horizon knows who is calling. An actor can be a user or a service account. API keys inherit access from the actor that owns them, so rotating a key changes the credential, not the actor's role. Horizon uses roles in three places: Controls organization-wide management, including members, invitations, billing contact assignment, SSO, service accounts, connectors, and server role definitions. Controls access to a specific server, including who can view it, update it, deploy it, manage access, or administer server settings. Controls which MCP tools, resources, and prompts are visible to each server role after the actor has server access. Custom server roles and team server grants are available on {serverRolesPlans}. Tool-level access is available on {toolAccessPlans}. ## Decision flow When Horizon evaluates access, it works from the broadest boundary to the specific action. The actor must belong to the organization. Actors outside the organization cannot use or manage its resources. Organization admins can manage organization settings and are treated as the `admin` server role on every server in the organization. Organization members continue to server-specific access checks. For non-admin members, Horizon combines an explicit server grant with roles granted to each Team they belong to. If no explicit or team grant exists, Horizon uses the server's default role. If none applies, the actor has no access to that server. If capability access is configured, Horizon allows a tool, resource, or prompt when its policy permits at least one of the actor's resolved server roles. Server access resolves in layers. Horizon checks organization access first, combines all explicit and team grants next, and uses the default role only when no grant applies: | Order | If | Resulting access | | ----- | ------------------------------------------------- | ---------------------------- | | 1 | The actor is an organization admin | `admin` on every server | | 2 | Explicit or team server grants exist | The set of all granted roles | | 3 | No grant exists and the server has a default role | The default role | | 4 | None of the above | No access | The organization and server planes compose independently. An organization admin reaches every server as `admin` without an explicit or team grant and cannot be locked out of one. An organization member reaches a server through an explicit grant, one or more team grants, or the server's default role. They hold no organization-management permissions regardless of their server roles. For example, a member granted `admin` on one server can fully administer that server but still cannot invite members or change the billing contact, while an organization admin can do both without appearing in that server's access list. For the full request path, see [Authorization](/platform/authorization). ## Organization roles Organization roles answer: "What can this actor manage across the organization?" | Role | Contract | | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Admin | Can manage organization settings and has full access to every server in the organization. Horizon evaluates organization admins as the `admin` server role for server and capability access. | | Member | Can read basic organization information and can access servers through explicit grants, team grants, or server default roles. | Use the Admin role for people and service accounts that should manage broad organization concerns such as membership, billing contact assignment, [single sign-on](/administration/sso), service accounts, connectors, and custom server roles. Admins cannot be hidden from individual servers in that organization. The [billing contact](/billing-contact) is separate from organization roles. Organization admins can reassign the contact, while the contact manages payment methods, plans, add-ons, and invoice emails. Organization role changes affect the next authenticated Horizon dashboard, REST API, or MCP request that resolves the actor's current access. [Directory Sync](/administration/directory-sync) can provision organization membership and synchronize identity provider groups as directory-backed Teams. WorkOS IdP Role Assignment can assign the organization roles Admin and Member. Where team access is enabled, Team grants can assign server roles and coexist with explicit grants. Connecting a directory does not create those server grants. ## Server roles Server roles answer: "What can this actor do with this server?" Horizon includes three built-in server roles. Built-in roles are available in every organization and cannot be edited. | Role | Slug | Server management | MCP endpoint access | | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | Admin | `admin` | Full server access, including access management, configuration, builds, capability policies, and deletion. | Can call the server and all capabilities. The `admin` role stays allowed in capability policies so administrators can recover access. | | Editor | `editor` | Can view and update server configuration, create builds, and edit capability policies. Editors cannot grant or revoke server access and cannot delete the server. | Can call the server. Capability policies can allow or deny specific tools, resources, and prompts for this role. | | Viewer | `viewer` | Can view the server, its access list, and its capability policy. Viewers cannot modify the server. | Can call the server. Capability policies can allow or deny specific tools, resources, and prompts for this role. | `No Access` is a server default setting, not a role. Use it when the rest of the organization should have no server access unless they receive an explicit or team grant. ## Custom server roles Custom server roles are organization-scoped server roles. Use them when the built-in Admin, Editor, and Viewer roles are too broad for a server management workflow. Each custom role has: | Field | Contract | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Name | Stable role slug used in API responses and capability policies. It must be lowercase alphanumeric with optional hyphens or underscores. Built-in slugs such as `admin`, `editor`, and `viewer` are reserved. The name cannot be changed after creation. | | Label | Human-readable name shown in Horizon. The label can be updated. | | Permissions | Server management permissions for the role. Horizon always includes the `read:access` permission, which the dashboard shows as **Read access**. You cannot remove it. This permission lets role holders view server access assignments. Updating permissions changes what holders of the role can do in Horizon. | Custom roles can be used as a server default role, assigned through explicit or team server grants, and referenced by capability access policies. Server role permissions control Horizon management actions. They do not decide which individual MCP tools, resources, or prompts a caller can use. Capability access handles that narrower decision. Before deleting a custom role, remove it from server defaults, explicit grants, and team grants. Also review capability policies that mention the role slug, so stale policy entries do not remain after the role is gone. ## Default role A server's default role is the access level given to the rest of the organization when an actor has no explicit or team grant for that server. Set the default role from a server's Access > Members page. Only organization admins and actors with explicit or team server grants can access the server. Every current and future organization member gets that server role unless they receive access through an explicit or team server grant. For sensitive servers, start with `No Access` and grant access only to the users, Teams, or service accounts that need it. For broadly shared servers, use a default role that matches the access most organization members should have. Default role changes are saved in Horizon and then applied to live server access metadata. No code change is required. ## Explicit server grants Explicit grants are actor-specific access entries on a server. Use them for exceptions to the default role, such as a service account that can deploy a server while the rest of the organization can only view it. Manage explicit grants from a server's Access > Members page. An explicit grant contributes one role and takes precedence over the server default role. If you remove it, the actor may still keep access through a team grant, the server default role, or organization admin access. ## Team grants A team grant assigns one server role to every current member of a Team. A person receives roles from every Team with a grant on that server, combined with any explicit grant they hold. These roles form a set rather than replacing one another. Directory Sync can manage the membership of a directory-backed Team, but it never creates, changes, or removes the Team's server grants. Removing a person from the identity provider group removes the corresponding team-derived role after membership synchronization without changing the grant for the remaining Team members. Team server grants are available on {serverRolesPlans}. Add, change, or remove a Team grant from the server's Access > Members page. Review all server grants for one Team from Govern > Teams by selecting the Team and opening its Servers tab. ## Capability access Capability access answers: "Which MCP tools, resources, and prompts can these server roles use?" It is evaluated after Horizon has resolved the actor's server role set. Capability policies can set default access for all capabilities, then override individual tools, resources, and prompts. A capability is available when its policy allows at least one role in that set. When no capability policy is configured, Horizon does not filter the server's capabilities by role. After a policy is configured, a capability without a matching default or override is denied. Resource templates use the resource access settings. For hosted servers, saved capability policy changes are visible in Horizon immediately, but MCP endpoint traffic uses the updated policy after the next deployment. Server default role, explicit grant, and team grant changes do not require a redeploy. ## Where to manage roles | Task | Horizon location | | ----------------------------------------- | --------------------------------------------- | | Change a user's organization role | Organization settings > Members | | Create or edit custom server roles | Organization settings > Roles | | Set a server default role | Server > Access > Members | | Add or update explicit server grants | Server > Access > Members | | Add, update, or remove Team server grants | Server > Access > Members | | Review a Team's server grants | Govern > Teams > select a Team > Servers | | Set tool, resource, and prompt access | Server settings > Authorization > Permissions | ## Related docs Learn the full request decision model for Horizon management and MCP endpoint traffic. Invite, remove, and review people in your organization. Create bearer credentials that inherit access from their owning actor.