API Keys

About API Keys

API keys let you authenticate programmatic requests to Governance Studio without using your login credentials. Any user can generate their own API keys from their User Profile.

Generating a key requires you to select at least one scope, which limits the key to a subset of the permissions you already hold. Keys with no scopes at all — legacy keys, and keys created directly against the Auth Service API — impersonate you fully until they expire, the opposite of a GitHub-style empty selection. Either way, an API key can never do more than its owner is authorized to do in the interface — for example, an API key generated by an Implementation Owner cannot be used to create a review as only Audit roles have that permission. Learn more about Roles and Permissions.

Treat API keys like passwords: store them in a secrets manager, avoid sharing them between users, rotate them when ownership changes, and revoke any key that has been exposed or is no longer in use.

Key concepts and actions associated with API keys include:

• Generating an API Key
• Registering Agents
• Viewing API Keys
• Revoking an API Key
• Service Accounts

Generating an API Key

To generate an API key:

1. Select the profile dropdown → Select User Profile
2. Under API Keys, select Generate API Key
3. Enter a Name
4. Enter a Description explaining what the key will be used for
5. Choose an Expiration. A key always expires; pick a preset or a custom date up to 365 days out
6. Choose an Access level. Organization — the default — lets the key work across every project you can access and use organization-wide scopes. Project binds the key to one project you then pick, and hides the organization-wide scopes a project binding cannot narrow. This field only appears if you belong to at least one project; otherwise the key is organization-scoped
7. Pick Scopes. At least one is required. Include Register Agents if this key will enroll agents; that scope is organization-level, so mint the key with Organization access
8. Select Generate Key

Once generated, your key is shown once. Copy and store it securely — Governance Studio does not display the full key value again.

Scopes

A key can hold one of three kinds of scope. Only the first is available in the dialog, which offers the scopes you can grant and requires at least one.

• Fine-grained: existing permission names such as register_agents, view_project_data, and create_policies, plus Read DIDs (did:read) when you are not a pure agent operator. Check the ones this key should use. For enrollment, check Register Agents.
• Empty (nothing checked): unrestricted access, the same as keys created before scopes existed. The dialog no longer generates these; you will still see them on older keys. An empty-scope key cannot register agents.
• Full access (*): Organization Owners only, and no longer offered in the dialog. An Organization Owner who needs it can send "scopes": ["*"] to the Auth Service API. It is exclusive — it cannot be combined with another scope or bound to a project — and it also enrolls agents.

An Agent Operator who holds no other role sees and can mint only Register Agents. Someone who is both an Agent Operator and a Project Owner still sees the project-owner scopes they hold, including View Project Data for the selected project.

Project access hides the scopes that a project binding cannot narrow — organization-level actions such as Register Agents, and Read DIDs. Switch to Organization access if the key needs them.

You cannot change scopes after a key is created. Revoke the key and generate a new one.

Prefer a short expiration and one enrollment key per agent or pipeline. Do not share a single key across unrelated fleets — scope each one to the narrowest set of permissions that does the job.

Registering an Agent with a Key

A key with the Register Agents scope (or Full access) can enroll a gateway agent from CI or a remote shell:

GUARDIAN_API_KEY=ak_… viper did register --app proxy --agent-name "checkout-bot"

Guardian mints the agent ID (urn:uuid:). Revoking the key does not remove agents that were already enrolled with it. For the full walkthrough, including the Governance Studio registration-token path and associating an agent with a project, see Register Agents.

Viewing API Keys

API Keys lists every key you’ve generated, along with:

• Key ID: A partial, non-sensitive identifier used to distinguish keys (for example, ak_d76f31a3...)
• Created: When the key was generated
• Last Used: The most recent time the key was used
• Expires / Expired: When the key expires, or when it expired
• Revoked: When the key was revoked
• Status: Active, Expired, or Revoked
• Scopes: Unrestricted (legacy) when empty, Full access when *, otherwise a chip for each selected permission
• Project: All projects, or the project the key is bound to

Use the search bar to find a key by name, description, or ID, or filter the list by status.

Revoking an API Key

Revoking a key is permanent and cannot be undone. Revoking a key does not remove agents that were already enrolled with it.

To revoke an API key:

1. Under API Keys, locate the key and select Revoke
2. Type the key’s name to confirm
3. Select Revoke

Service Accounts

Some platform integrations use service accounts rather than user-owned API keys. Service accounts are managed by platform operators and documented with Auth Service. They are not a replacement for assigning correct project roles to human users.