Roles

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:

​

Decision flow

When Horizon evaluates access, it works from the broadest boundary to the specific action. 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: 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.

​

Organization roles

Organization roles answer: “What can this actor manage across the organization?” Use the Admin role for people and service accounts that should manage broad organization concerns such as membership, billing contact assignment, single sign-on, service accounts, connectors, and custom server roles. Admins cannot be hidden from individual servers in that organization. The 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.

​

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

​

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

​

Where to manage roles

​

Related docs