Members, Roles, and Permissions
Learn which roles have which permissions and how to invite and remove organization members
A GraphOS organization can have any number of members, and each member can be assigned a role that defines their capabilities within the organization.
Organization-wide member roles
Each organization member has one of the following roles:
| Name | Description | Supported plan types |
|---|---|---|
| Org Admin | Has management access to the entire organization, including its members, graphs, and configuration. | All |
| Graph Admin | Has management access to the organization's graphs, but not to members or organization-level configuration. Intended for developers who are considered admins to the graph. | Enterprise only |
| Contributor | Can push new schemas to graphs, but cannot configure graph settings or integrations. Intended for backend developers who are authorized to make changes to graphs. Cannot push schema changes or report metrics for protected variants. | Enterprise only |
| Documenter | Has all permissions of the Observer role, plus the ability to edit graph READMEs, descriptions, and similar non-operational metadata. | Enterprise only |
| Observer | Has view-only access to the organization's graph data, such as schemas and metrics. Can also execute queries in the Explorer. Intended for backend developers who are not authorized to make changes to graphs. | Enterprise only |
| Consumer | Has view-only access to the organization's API schemas, but not supergraph or subgraph schemas, or metrics. Can also execute queries in the Explorer. Intended for application developers building clients against a graph.This role is available to all plan types. For plans that charge per user, Consumers do not count as billed users. | All |
| Billing Manager | Has management access to organization-level configuration and billing. Can also remove members (but not invite them). No access to graphs. Learn more.This role is available to all paid plan types. For plans that charge per user, Billing Managers do not count as billed users. | All paid plan types |
Only members with the Org Admin role can assign roles to other members. You can see which role you have in a particular organization from your user settings page, or from the organization's Members tab.
Graph-specific member roles
You can override a member's organization-wide role for individual graphs. For example, if a member has the Observer role in your organization, you can assign them the Contributor role for a graph that they need extra access to.
ⓘ NOTE
A member's graph-specific role must have more permissions than their organization-wide role.
Members with the Graph Admin or Org Admin role can assign graph-specific roles from the Permissions tab of the graph's Settings page.
Hidden graphs
If a graph is made hidden, then only users with explicit overrides (as well as Org Admins) can see the graph.
Graph admin override
The Graph Admin and Org Admin roles have exactly the same permissions for a particular graph, so you can only grant a Graph Admin override, not an (equivalent) Org Admin override.
Default on graph creation
When Contributors in an organization create a new graph, they are automatically granted the Graph Admin role for that graph.
Role permissions
Organization management permissions
| Action | Org Admin | Graph Admin | Contributor | Observer / Documenter | Consumer |
|---|---|---|---|---|---|
| Manage organization configuration (name, avatar, etc.) | ✓ | ||||
| Delete the organization | ✓ | ||||
| View and edit billing information | ✓ | ||||
| Invite members | ✓ | ||||
| Remove members | ✓ | ||||
| Export audit logs (enterprise only) | ✓ | ||||
| Manage which users have access to graphs | ✓ | ✓ |
Graph management permissions
| Action | Org Admin | Graph Admin | Contributor | Observer / Documenter | Consumer |
|---|---|---|---|---|---|
| View and manage graph API keys | ✓ | ✓ | |||
| Manage graph integrations (Slack, Datadog, etc.) | ✓ | ✓ | |||
| Delete and rename graphs | ✓ | ✓ | |||
| Create graphs | ✓ | ✓ | ✓ | ||
| Create new variants | ✓ | ✓ | Non-protected variants only | ||
| Push schemas to a graph | ✓ | ✓ | Non-protected variants only | ||
| Manage Explorer settings (URL, etc) | ✓ | ✓ | Non-protected variants only | ||
| Report graph usage metrics 1 | ✓ | ✓ | Non-protected variants only | ||
| See the schemas of subgraphs in federated graphs | ✓ | ✓ | ✓ | ✓ | |
| View graph usage metrics and traces 2 | ✓ | ✓ | ✓ | ✓ | |
| Edit variant READMEs | ✓ | ✓ | ✓ | Documenter only | |
| Query graphs with the Explorer | ✓ | ✓ | ✓ | ✓ | ✓ |
| View graph schemas and changelogs | ✓ | ✓ | ✓ | ✓ | ✓ |
ⓘ NOTE
When you report metrics from Apollo Router or Apollo Server you should use a graph API key. For non-protected variants, the graph API key role must be Contributor, Org Admin, or Graph Admin. For protected variants, only Org and Graph Admin roles can report metrics.
Currently, graph usage metrics and traces are not displayed to Consumers via the Studio web app, but they are not blocked at the API layer. We intend to remove this capability from Consumers, but for the time being you should understand that Consumers are not fully prevented from accessing these metrics and traces.
Schema checks permissions
Learn more about schema checks.
| Action | Org Admin | Graph Admin | Contributor | Observer / Documenter | Consumer |
|---|---|---|---|---|---|
| Modify schema checks configuration | ✓ | ✓ | |||
| Override flagged checks | ✓ | ✓ | |||
| Run schema checks | ✓ | ✓ | ✓ | ✓ |
Schema proposals permissions
This feature is only available with a GraphOS Enterprise plan.
You can test it out by signing up for a free Enterprise trial.
The table below shows default schema proposal settings. You can configure which roles can create, edit, and approve proposals.
| Action | Org Admin | Graph Admin | Contributor | Observer / Documenter | Consumer |
|---|---|---|---|---|---|
| Change proposal status | ✓ | ✓ | |||
| Create proposals | ✓ | ✓ | ✓ | ✓ | |
| Edit proposals | ✓ | ✓ | ✓ | ✓ | |
| Add reviewers | ✓ | ✓ | ✓ | ✓ | |
| View proposals | ✓ | ✓ | ✓ | ✓ | ✓ |
| Make comments | ✓ | ✓ | ✓ | ✓ | ✓ |
| Approve proposals | ✓ | ✓ | ✓ | ✓ | ✓ |
Contract permissions
This feature is only available with a GraphOS Enterprise plan.
You can test it out by signing up for a free Enterprise trial.
Learn more about contracts.
| Action | Org Admin | Graph Admin | Contributor | Observer / Documenter | Consumer |
|---|---|---|---|---|---|
| Create and modify contracts and contract variants | ✓ | ✓ | |||
| View existing contracts | ✓ | ✓ | ✓ |
Billing managers
Members with the Billing Manager role can't see or manage graphs in their organizations, but they can:
- Remove members from the organization
- View and edit billing information (including changing the billing plan)
- Manage organization configuration (name, avatar, etc.)
Notably, Billing Managers can't invite new members to the organization or update roles.
Graph API key roles
Each graph API key also has a corresponding member role. This role can be any of Graph Admin (the default), Contributor, Documenter, Observer, or Consumer. A graph API key provides access only to its associated graph. It does not provide access to actions associated with organizations or users.
An additional role called Persisted Query Publisher is only available for graph API keys, not for organization members. The role is only available for API keys for graphs in Enterprise organizations. API keys with this role can run the rover persisted-queries publish command to publish operations to persisted query lists. The role provides no other read or write access to the graph.
This role is appropriate for use in client development teams' deployment processes. If your graph uses persisted queries, some client teams may need to publish their operations to your graph's persisted query lists but should not be able to view your graph's schema, changelogs, or use other Consumer-level features.
Otherwise, a graph API key is equivalent in privileges to a user with the same role for the graph. For example, you can use a Consumer key to fetch a graph's schema, and you can use a Graph Admin key to manage integrations.
A few operations aren't listed in the table above because they are only supported by graph API keys, not personal API keys for users in the graph's organization. These are primarily operations that are performed by your GraphQL server, such as usage reporting (traces and performance metrics).
ⓘ NOTE
Before January 2021, graph keys did not have roles. Keys created before that date (shown as Legacy Admin keys) can perform the following operations:
- Create new variants
- Run schema checks
- View and manage graph API keys
- Push schemas to a graph
- See the schemas of subgraphs in federated graphs
- View graph schemas and changelogs
- Modify schema checks configuration
Inviting members
Org Admins can invite individual members by email address from your organization's Members tab in GraphOS Studio. Organization admins can also create a persistent invite link from the organization's Settings tab, which can be used to invite any number of members. Using either method, an org admin can specify which role a new member receives.
ⓘ NOTE
- If your organization uses an identity provider (IdP) for single sign-on (SSO), you should configure access in your IdP rather than via invitations. For example, with Okta, you need to assign members to your GraphOS Studio integration to give them access. If you've configured a member to have access in your IdP, they can access GraphOS Studio without an invitation link.
- Do not share invite links publicly. Anyone with the link can join your organization. If an invite link becomes compromised, an admin can replace or turn it off from the Settings tab.
Removing members
Both Org Admins and Billing Managers can remove members from your organization's Members tab in GraphOS Studio.