Skip to content
Governance Platform

API Keys and Service Accounts

API keys and service accounts support machine-to-machine access. They should be used only when an interactive user session is not appropriate.

API Keys

Section titled “API Keys”

API keys are tied to platform access and should be treated as secrets. An API key acts on behalf of the user who created it, limited to the scopes chosen at creation, so it is sometimes called a user API key. Use them for integrations that act with a defined platform identity.

  • Empty scopes keep legacy unrestricted behavior, in which the key impersonates the user. They do not enroll gateway agents.
  • Named scopes are RBAC permission names the creator can grant (for example register_agents, view_project_data), plus did:read when the caller is not a pure agent operator. A scoped key is deny-by-default outside that list.
  • * is explicit full access, available to organization owners only.
  • projectId binds project-level permissions to one project. Organization-level actions such as register_agents still apply across the organization. Omit projectId (Organization only) for every project the holder can already access.
  • API keys cannot create or revoke API keys. Create keys with a user session.

For enrollment, a key with register_agents or * may call the gateway with Authorization: Bearer ak_…. Both the key scope and the owner’s RBAC grant are required, and empty-scope keys cannot enroll. Create the key from Governance Studio (User Profile → API Keys) or the Auth Service API using a user session.

Recommended practices:

  • Store keys in a secrets manager.
  • Prefer a short expiry and one key per agent or pipeline.
  • Rotate keys when ownership or system responsibility changes.
  • Revoke unused keys. Revoking a key does not unwind agents already enrolled with it.
  • Avoid sharing a single key across unrelated integrations.

Service Accounts

Section titled “Service Accounts”

Service accounts are for trusted platform services, such as backend workers that need to call another platform service. Operators configure service accounts as part of deployment and operations.

Do not use service accounts for normal human user access. Human users should sign in through the identity provider and receive project roles.

Choosing Between Them

Section titled “Choosing Between Them”

Use a user API key when the integration should be accountable to a user or customer-managed integration identity. Use a service account when the integration is a platform service that must operate independently of a human user.