# Service accounts Source: https://docs.graphops.xyz/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](https://platform.graphops.xyz/organizations/current/organization/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](#create-an-api-key). A service account calls only the GraphOps platform API. Your applications query data services with [query keys](/platform/api-keys#query-keys-and-service-account-api-keys). ## Create a service account You need the owner or developer role. 1. Open [Service accounts](https://platform.graphops.xyz/organizations/current/organization/service-accounts), under **Organization**, and create a service account. 2. 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. 3. Choose its permissions. See [Choose permissions](#choose-permissions). 4. Optionally, limit permissions that act on Managed Subgraphs and Endpoint Aliases. See [Limit permissions to Managed Subgraphs](#limit-permissions-to-managed-subgraphs). 5. Create the account. The last step shows its permissions by category; then [create an API key](#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](/platform/team-and-roles#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 | | 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 | | Managed Subgraphs | Rename Managed Subgraphs | Rename Managed Subgraphs. | To Managed Subgraphs | | Managed Subgraphs | Stage deployments | Stage a deployment as Next, which is billed while it indexes. | To Managed Subgraphs | | Managed Subgraphs | Cancel Next | Cancel a staged Next version. | To Managed Subgraphs | | Managed Subgraphs | Promote Next | Promote Next to Current, which changes what your queries are served. | To Managed Subgraphs | | 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 | | 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 | | Endpoint Aliases | Create Endpoint Aliases | Create Endpoint Aliases for a Deployment CID, a Managed Subgraph, or a Graph Network Subgraph ID. | To Managed Subgraphs | | Endpoint Aliases | 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 | | 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 | | 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 | | API keys | Rename API keys | Rename API keys. | No | | API keys | 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. 1. Open the service account in [Service accounts](https://platform.graphops.xyz/organizations/current/organization/service-accounts) and choose **Create API key**. You can also choose **Create API key** in **API keys**, then **Service account API key** and the account. 2. Give the key a label that names where it runs, such as `github-ci` or `reports-server`. 3. 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`](/platform/errors/api-keys#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](/platform/api-keys#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 `). 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](https://platform.graphops.xyz/organizations/current/organization/service-accounts), 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](https://platform.graphops.xyz/organizations/current/organization/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](/platform/account-and-security#sign-in-again-for-sensitive-changes) 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. ## Next steps * [API keys](/platform/api-keys): Rotate and revoke service account API keys alongside your query keys. * [Team and roles](/platform/team-and-roles#roles): Compare what each role and a service account can do. * [Develop and release a Subgraph](/subgraphs/guides/develop-and-release): Stage, test, and promote new versions of a Managed Subgraph.