Permissions

A permission is named <resource>:<action>. A member’s role carries a set of them, and so does an API key. The GraphPilot API checks them on every operation, and the portal hides or disables most controls a member may not use. Which role holds which permissions is in the table under members and roles.

Each resource has two levels: view reads it, and edit changes it and includes view. A role still lists both: a key can only be given permissions the member creating it holds by name, so a role with service:edit alone could not create a read-only key. Three permissions stand on their own because of what they do: deleting a service, deleting the organization, and purging.

Permissions

Permission	Allows
service:view	Seeing the organization’s services and reading them through the API, including ipRanges, purges, custom domains, telemetry and the persisted query registry. Without it, services are not visible and lists come back empty.
service:edit	Everything service:view allows, and creating a service (within the plan’s allowance), changing its settings, origin, custom domains, alert rules and persisted query manifest, uploading the schema and configuration every deployment starts with, reading the deployed configuration back, and seeing (masked), rotating and activating its signing key. It does not include deleting a service or purging.
service:delete	Deleting a service, with a confirmation code, and resetting a service’s history. Includes seeing the organization’s services, not their custom domains.
deployment:view	Seeing deployments (Deployments), what each one built, its diagnostics and configuration analysis, and the portal’s Schema and Config pages. Through the API, the live deployment’s schema and analysis on the service (Service.deployedSchema, Service.schemaAnalysis, Service.configAnalysis) need only service:view.
deployment:edit	Everything deployment:view allows, and starting a deployment, canceling one that is still in progress, and tearing down a service’s deployed edge infrastructure while keeping the service.
cache:purge	Every purge. service:edit does not include it.
organization:edit	Changing the organization’s settings.
organization:delete	Deleting the organization, with a confirmation code.
billing:view	Seeing the plan, payment method and billing address.
billing:edit	Everything billing:view allows, and changing the plan, payment method and billing address.

Earlier permission names

Roles and API keys set up before October 2026 can carry the earlier, finer-grained names. They keep working for now, each allowing what it allowed before, and will stop being accepted once every role and key has moved to the names above. A key that carries one should be replaced with a key that carries the new name.

Earlier name	Now part of
service:create, service:view-signing-key, service:rotate-signing-key, service:activate-signing-key	service:edit
service:manage	service:edit and service:delete
deployment:create, deployment:delete, deployment:cancel-deployment, deployment:manage	deployment:edit
organization:manage	organization:edit and organization:delete
billing:manage	billing:edit

Your own account is not governed by permissions: anyone can delete their own account. See your account.

What an API key can carry

An API key can carry these six permissions:

service:view, service:edit, deployment:view, deployment:edit, cache:purge, billing:view

Everything a person decides, such as organization settings, billing changes or deleting a service, is not available to a key. A key holding service:edit cannot see, rotate or activate the signing key: those parts of service:edit are removed from every API key. A key holding service:edit can read the deployed configuration back, as a member can. Deleting a service, an organization or an account also needs a confirmation code, which an API key cannot request or spend (FORBIDDEN). The earlier names service:create, deployment:create and deployment:delete are still accepted on a key while they are being phased out.

How a missing permission shows

Where	What happens
A read through the API	Filtered, not refused: a key without service:view sees no services, not an error.
A mutation through the API	Refused with FORBIDDEN. See codes.
The gpilot CLI	The API’s error is printed and the CLI exits with 4. See exit codes.
The portal	The control is hidden or disabled; a disabled one says why when you point at it.

Jobs

What each job needs. Every CLI command that takes --service looks the service up first, which needs service:view.

Job	CLI	API	Permissions
Deploy	gpilot deploy	createSchemaUploadUrl, createConfigUploadUrl, createDeployment, deploymentProgress	service:edit (uploads the schema and configuration) and deployment:edit (starts the deployment and waits for the result)
Cancel a deployment	gpilot deployment cancel	cancelDeployment	deployment:edit
Tear down the edge infrastructure	gpilot service destroy	destroyDeployment	deployment:edit
Pin or unpin the runtime version	gpilot service runtime pin, gpilot service runtime unpin	setServiceRuntimePin	service:edit and deployment:edit (changing the pin can redeploy the service, and decides what its next deployment builds)
Read a deployment’s diagnostics	gpilot deploy output	Deployment.diagnostics, Deployment.configAnalysis	service:view, deployment:view
Read the deployed configuration	gpilot config get, the portal’s gpilot.toml views	createConfigDownloadUrl, Deployment.configDocument	service:edit, for members and API keys alike. Every resolved setting, secrets redacted, needs only deployment:view (configAnalysis, the portal’s Config values).
Purge the cache	gpilot purge	purgeBySurrogateKey, purgeByQueryHash, purgeByRequest, purgeAll, POST /purge	cache:purge
Read the purge history		Service.purges	service:view
Push persisted queries	gpilot pq push	pushPersistedQueries	service:edit
Revoke persisted queries	gpilot pq rm, gpilot apq rm	removePersistedQueries	service:edit
List persisted queries	gpilot pq list, gpilot apq ls	Service.persistedQueries, Service.clientRegisteredQueries	service:view
Create a service	gpilot service create	createService	service:edit
Read request telemetry	gpilot requests	Service.requests, serviceRequestsStream	service:view; some filters also need a plan, see Insights
Read the origin IP ranges		Service.ipRanges	service:view
Manage custom domains		addServiceDomain and the other domain mutations	service:edit
Switch an alert rule on or off		setAlertRuleEnabled	service:edit; reading the rules (Service.alertRules) needs service:view
See the signing key, masked		Service.signingKey, Service.pendingSigningKey	service:edit
Rotate the signing key, or cancel a rotation		rotateServiceSigningKey, cancelServiceSigningKeyRotation	service:edit
Activate a pending signing key		activateServiceSigningKey	service:edit
Delete a service	gpilot service delete	requestActionConfirmation, deleteService	service:delete and a confirmation code; a member, not an API key
Reset a service’s history		resetServiceHistory	service:delete; a member, not an API key

The signing-key rows are for members only: an API key that carries service:edit still cannot do them.