Platform: Service accounts

Let your CI pipelines, automation, and servers manage GraphOps without borrowing a person's account. A service account is your organization's identity for one such workload. It holds only the permissions the workload needs, such as staging new versions of your Managed Subgraphs, and keeps them while you add, rotate, and revoke the credentials it signs in with.

Open Service accounts

A service account signs in to the GraphOps platform API with a service account API key (gsk_), which you store as a secret in your CI system or server. See Create an API key.

A service account calls only the GraphOps platform API. Your applications query data services with query keys.

Create a service account

You need the owner or developer role.

Open Service accounts(opens in a new tab), under Organization, and create a service account.
Name it after its workload, such as ci-deploy or usage-reports, in up to 64 characters. Names must be unique within the organization. Optionally, add a description of up to 280 characters, such as the team that owns the workload.
Choose its permissions. See Choose permissions.
Optionally, limit permissions that act on Managed Subgraphs and Endpoint Aliases. See Limit permissions to Managed Subgraphs.
Create the account. The last step shows its permissions by category; then create an API key for it to sign in with.

Choose permissions

A service account holds only the permissions you choose. It can hold any permission a member's role can, except the ones only a person can use and running explorer queries; Team and roles marks them. Permissions are grouped by what they act on:

Area	Permission	What it allows	Can be limited
Organization	Read organization overview	Read the organization's overview: its plan status, credit balance, and API key counts.	No
Services	Read data services	Read the data services available to the organization.	No
Usage	Read usage	Read the organization's hourly, daily, and settlement usage.	No
Subgraphs	Read Subgraphs	Browse the public Subgraph catalog and read Subgraph metadata, schemas, and SDL.	No
Substreams	Read Substreams packages	Explore Substreams packages: their modules, networks, and versions.	No
Managed Subgraphs	Read Managed Subgraphs	List Managed Subgraphs, read their status, and validate a target or Next version.	To Managed Subgraphs
	Create Managed Subgraphs	Create Managed Subgraphs pinned to a Deployment CID. Each new one starts billing. Following a Graph Network Subgraph ID also needs Reconfigure Managed Subgraphs.	No
	Rename Managed Subgraphs	Rename Managed Subgraphs.	To Managed Subgraphs
	Stage deployments	Stage a deployment as Next, which is billed while it indexes.	To Managed Subgraphs
	Cancel Next	Cancel a staged Next version.	To Managed Subgraphs
	Promote Next	Promote Next to Current, which changes what your queries are served.	To Managed Subgraphs
	Reconfigure Managed Subgraphs	Change the target type: follow a Graph Network Subgraph ID, which stages and promotes new versions automatically, or pin a Deployment CID.	To Managed Subgraphs
	Delete Managed Subgraphs	Request a Managed Subgraph's deletion, which stops it serving queries.	To Managed Subgraphs
Endpoint Aliases	Read Endpoint Aliases	List Endpoint Aliases and their targets.	To Managed Subgraphs or Endpoint Aliases
	Create Endpoint Aliases	Create Endpoint Aliases for a Deployment CID, a Managed Subgraph, or a Graph Network Subgraph ID.	To Managed Subgraphs
	Retarget Endpoint Aliases	Point an Endpoint Alias at another target, which changes what it serves. Changing the target type also needs Reconfigure Endpoint Aliases.	To Managed Subgraphs or Endpoint Aliases
	Reconfigure Endpoint Aliases	Change an Endpoint Alias's target behavior, such as Current or Next. Changing its target type also needs Retarget Endpoint Aliases, because the target changes too.	To Managed Subgraphs or Endpoint Aliases
	Delete Endpoint Aliases	Delete Endpoint Aliases, which stops their names resolving.	To Managed Subgraphs or Endpoint Aliases
API keys	Read API keys	List every API key in the organization, query keys and service account keys, with its services, limits, service account, and creator, never their secrets. With Read usage, the holder also sees usage by API key.	No
	Rename API keys	Rename API keys.	No
	Revoke API keys	Revoke API keys, so automation can revoke a leaked key at once.	No
Service accounts	Read service accounts	List service accounts with their permissions, keys, creators, and last use.	No
Members	Read members	List the organization's members with their names, email addresses, and roles.	No
Invitations	Read invitations	List the organization's invitations with their email addresses and roles.	No
Billing	Read billing	Read the plan, credits, credit history, top-ups, notification settings, and billing catalog. A service account cannot open the payment link of a plan checkout in progress, preview a plan change, or open invoices. With Read usage, the holder also sees billing detail in usage.	No

Grant only what the workload needs. A pipeline that stages new versions for review needs Read Managed Subgraphs and Stage deployments, and Cancel Next to replace a version it already staged. Add Promote Next only if the pipeline should also switch production to the new version. Read members and Read invitations give the workload your team's email addresses. Read API keys and Read service accounts also show the names and email addresses of the people who created keys and service accounts, including members who have left. Grant these only to a workload that needs them.

Permissions belong to the service account, not to its API keys. Every API key of the account acts with the same permissions, so a change applies to all of them from their next request, and rotating a key never changes what the account can do.

Read an account's permissions

Lists show a service account's permissions as one badge per category, such as Managed Subgraphs, with a lock. Hover over or select a badge to see the permissions the account holds in that category and any limits. The service account's page lists every permission it holds by category, with what each one allows and its limits.

You can grant only permissions your own role includes; a developer, for example, cannot grant Read billing or Read members. A request that grants any other permission is refused with 403 and the code api_key_permission_not_held. A service account can never create or rotate keys, change a key's access, manage service accounts, change who belongs to your organization, or make payments. It can rename and revoke API keys when you grant those permissions, so incident automation can revoke a leaked key.

Limit permissions to Managed Subgraphs

Permissions that act on Managed Subgraphs or Endpoint Aliases can each be limited: turn on the permission's limit and choose the Managed Subgraphs, and for Endpoint Alias permissions that take them, the Endpoint Aliases it can act on. A request for anything else is refused with 403 and the code api_key_target_not_allowed, and a list shows only what the account can reach. A limit can list up to 100 Managed Subgraphs and 100 Endpoint Aliases. Create Managed Subgraphs cannot be limited, because a new Managed Subgraph does not exist until it is created.

An Endpoint Alias limit allows an alias when it is listed by name, or when every Managed Subgraph it serves, before and after the change, is listed. An account whose Create Endpoint Aliases permission is limited can create an alias only for a chosen Managed Subgraph. Any other alias change, including one that involves a Deployment CID or a Graph Network Subgraph ID the account cannot reach, is refused with 403 and the code api_key_target_not_allowed, and nothing changes.

The other permissions apply to the whole organization and cannot be limited. Read service accounts shows every service account's permissions and limits, so an account that holds it also sees which Managed Subgraphs and Endpoint Aliases other accounts are limited to.

Create an API key

A service account API key lets any CI system or server sign in as the account. A service account can hold several active keys, so you can replace one without a gap: create the new key, deploy it, confirm the workload succeeds, then revoke the old key.

Open the service account in Service accounts(opens in a new tab) and choose Create API key. You can also choose Create API key in API keys, then Service account API key and the account.
Give the key a label that names where it runs, such as github-ci or reports-server.
Review the key, then create it. Copy the key into your CI or server secrets when it is shown. You cannot retrieve the same key again.

You can create or rotate a service account's key only if your role includes every permission the account holds. Otherwise the request is refused with 403 and the code api_key_permission_not_held. A developer, for example, cannot create a key for an account that holds Read billing.

Service account API keys are listed with your other API keys in API keys, with the account each one belongs to. Rename, rotate, and revoke them there; see Rotate and revoke.

Use a service account API key

Use the key with the GraphOps CLI: set the GRAPHOPS_TOKEN environment variable to it, and the CLI acts as the service account, in the organization that owns the account, with only the account's permissions. A service account API key is sent to the GraphOps platform API as a bearer token (Authorization: Bearer <SERVICE_ACCOUNT_KEY>). A request that needs a permission the account does not hold is refused with 403 and the code organization_permission_insufficient.

In CI, such as GitHub Actions, store the key as a secret of your CI system and pass it to the job that runs the CLI as GRAPHOPS_TOKEN. Never commit the key to your repository.

Delete a service account

Deleting a service account revokes all of its API keys. Every workload that uses the account is refused from its next request. You cannot undo the deletion.

A deleted service account moves to the Archived tab of Service accounts(opens in a new tab), with the permissions it held and when it was deleted. Its page and its revoked API keys stay available, and usage and audit records keep its ID. Its name is free for a new service account.

Before you delete an account, check its Last used, the most recent UTC day any of its keys was used, and move any workload still using it to another account. Then open the account in

Service accounts

and delete it.

Who can manage service accounts

Owners and developers can see, create, edit, and delete service accounts and create their keys. Billing admins and viewers cannot see them. These changes are person-only, so no service account can make them, and GraphOps can ask you to sign in again first.

Each service account and key shows the person who created it. When that person's role changes or they leave the organization, the account keeps working with the same permissions. When a member leaves, review the keys on your service accounts and rotate or revoke the keys they could have copied.

Create a service accountCopy Anchor Link

Choose permissionsCopy Anchor Link

Read an account's permissionsCopy Anchor Link

Limit permissions to Managed SubgraphsCopy Anchor Link

Create an API keyCopy Anchor Link

Use a service account API keyCopy Anchor Link

Delete a service accountCopy Anchor Link

Who can manage service accountsCopy Anchor Link

Next stepsCopy Anchor Link