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.

By default, a new key with no scopes selected impersonates you fully until it expires — the opposite of a GitHub-style empty selection. Select scopes to limit the key to a subset of the permissions you already hold. 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 Key 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 a Project to limit project-level access to that project (the current project is selected by default). Organization-level actions such as registering agents still apply across the organization. Choose Organization only for every project you can access
7. Optionally pick Scopes. Leave them empty to impersonate you fully (legacy unrestricted); the dialog warns you when you do. Empty scopes cannot register agents — include Register Agents (or Full access) if this key will enroll
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

The picker only offers scopes you can grant.

• Empty (nothing checked): unrestricted access, the same as keys created before scopes existed. Generating still works; the warning is a reminder that the key impersonates you fully. An empty-scope key cannot register agents.
• Fine-grained: existing permission names such as register_agents, view_project_data, and create_policies, plus did:read when you are not a pure agent operator. Check the ones this key should use. For enrollment, check Register Agents.
• Full access (*): Organization Owners only. Exclusive — selecting it clears every other scope. 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.

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 full-access key across unrelated fleets.

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: Organization only, 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.