EQTY LabDocs

API Keys

Generate, view, and revoke API keys, choose their scopes, and use one to register an agent.

View as Markdown

About API Keys

API keys let you authenticate programmatic requests to the Guardian Platform without using your sign-in credentials. Any user can generate their own API keys from Settings.

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 through the Auth Service API without scopes — 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 determine a control’s outcome, as only Organization Owners, Project Owners, and Audit Owners 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
  • Using a Key from a Script
  • Viewing API Keys
  • Revoking an API Key
  • Service Accounts

Generating an API Key

To generate an API key:

  1. Select the profile dropdown → Select Settings
  2. Select 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

The Generate New API Key dialog with the name Agent enrollment, a description, a 30-day expiration, Organization access, and the Register Agents scope selected under Agent Management.

Once generated, your key is shown once. Copy and store it securely — Guardian 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, View Agent Certifications, and the two assessment scopes every member holds. Mint a key with View Agent Certifications and Organization access to let deploy automation pull the certifications of the agents you are bound to; a project-bound key cannot carry it. 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, View Agent Certifications and the assessment scopes, and Read DIDs. Switch to Organization access if the key needs them.

To drive agent certification from your own tools, choose the Program Management scopes for the part you play, with Organization access:

  • Submit Agent Assessments: start, draft and submit assessments of the agents you can see, and read those agents. Every member can choose it.
  • Review Agent Assessments: review assessments of the programs you’re assigned to review, and retry or revoke the certifications your reviews issued. Every member can choose it.
  • Manage Governance Programs: create programs, assign their reviewers, and retry or revoke any certification. Organization Owners hold it.

A key does only what you could do yourself: it submits only assessments you started and reviews only programs you’re assigned to. A scope counts only while you still hold that permission in the key’s organization, so a key stops working for a step as soon as you lose the role or membership it rests on, though it still lists the scope. Two steps take more than these scopes. Assigning a reviewer looks the member up with your key, which the Auth Service allows only a full-access key. A review that passes a submission signs its certification with the platform key on your key, which needs the key to cover every permission of a role that may sign; otherwise your review stands and an Organization Owner issues the certification. See Agent Assessments.

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:

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

The Guardian Platform 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 Guardian registration-token path and associating an agent with a project, see Register Agents.

Using a Key from a Script

Send the key in the Authorization header as a bearer token. To check which projects a key can use a permission on before you hand it to a pipeline, ask the Auth Service at your platform host followed by /authService:

bash
curl "https://guardian.example.com/authService/api/v1/rbac/permission/view_project_data/projects" \
  -H "Authorization: Bearer $GUARDIAN_API_KEY"
json
{
  "permission": "view_project_data",
  "projects": [{ "id": 15, "uuid": "fd47f68b-8760-4d0d-94fa-7658924acb25" }]
}

The list reflects the key’s scopes and project binding. An empty list means the key cannot read any project’s data. For what each service accepts a key for, see API Keys and Service Accounts.

Viewing API Keys

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

  • Name: The name you gave the key
  • Key ID: A partial, non-sensitive identifier used to distinguish keys (for example, ak_d76f31a3...)
  • Access: Organization, or the name of the project the key is bound to
  • Created: When the key was generated
  • Expiration: When the key expires, counting down while it is active. Older keys created without an expiration show No expiry
  • Last Used: For an active key, the most recent time it was used, or Never. An expired or revoked key shows Expired or Revoked instead

Use the search bar to find a key by name or ID, filter the list by Status, or sort by Created, Expiration, or Last Used.

Select a key to open its details, which add:

  • Key Status: Active, Expired, or Revoked
  • The key’s description and any allowed IP addresses
  • When the key was last used, and how many requests it has made
  • When the key was revoked, and why
  • Every scope the key holds
  • Timeline: When the key was created and when it expires

The API Keys section of Settings, listing three keys with their names, ak_ key IDs, access level or bound project, creation date, expiration, and when each was last used.

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. In Settings, select API Keys, then select the actions menu (⋮) on the key’s row → Select Revoke API Key, or open the key and select Revoke API Key
  2. Type the key’s name to confirm
  3. Optionally, enter a Reason for revocation. If left blank, the reason is recorded as “Revoked by user”
  4. 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.