API Keys

Create scoped API keys for scripts that read risks, read policies or create policies.

Who can use this screen

Administrators can open Settings → API Keys, create keys, rotate their secrets and revoke them. The screen requires API access on your licence. Each key belongs to its original creator. Every request also checks that owner’s current employee permissions, the relevant module and API access. A key cannot grant permissions that its owner no longer has.

Supported operations

Operation Scope to select Endpoint
Read risks read:risks GET /api/risks
Read policies read:policies GET /api/policies
Create policies write:policies POST /api/policies

These are the complete set of operations supported by API keys. Use the existing session-based application for other operations, including key management. Select only the operations your script needs.

Create a key

  1. Enter a descriptive Key Name, up to 100 characters.
  2. Under Allowed operations, select at least one operation. No operation is selected automatically.
  3. Optionally choose an expiry using your local time. Leave it empty for no expiry.
  4. Set Admissions per UTC hour between 1 and 10,000. The default is 100.
  5. If IP restrictions are available, optionally enter one exact IPv4 or IPv6 address per line. Ranges are not supported. Leave the field empty for no IP restriction. A disabled field means the required ingress configuration has not been verified.
  6. Select Create Key. The full secret appears once in a green banner.
  7. Select Copy & Dismiss and save the key in your script’s secret store. The banner closes after a successful copy. If copying fails, the key remains visible so you can copy it before leaving.
Save the secret before leaving

The full key cannot be recovered later. Aegis stores its hash and displays only a prefix afterward. If you lose the secret, rotate that key to issue a replacement secret without changing the key itself, or revoke it and create a new one. Do not put it in an email, ticket, URL or source-code repository.

Use a key

Send the secret in the HTTP header Authorization: Bearer aegis_…. The full value consists of aegis_ followed by 64 lowercase hexadecimal characters. The x-api-key header is not supported. The documented endpoints use the same request fields and response data as their session-based equivalents.

Creating a policy sets its owner to the key’s original owner. The audit trail identifies that employee and records that an API key performed the operation.

Read the key list

The API Keys table starts with the Active status filter. Select All to include revoked and expired history. Each row shows the prefix, creation and last-use dates, selected operations, expiry, admission count and hourly limit. Availability describes the current owner and module state; the server checks these again when a request arrives.

A row marked Reissue required is historical configuration that cannot authenticate. Create a new key with explicit allowed operations. Existing names, scopes and historical counts remain visible; historical usage counts do not have the same meaning as current admission counts.

Understand the hourly limit

An admission is a validated request allowed to begin its operation. Invalid input and authentication or entitlement failures do not consume a key admission. A failure after the operation begins does consume one. The bucket resets on each UTC hour, and Last Used records the last admission. The response includes the remaining limit and reset time. If the hourly quota is exhausted, HTTP 429 includes Retry-After.

Do not automatically retry policy creation after an uncertain response: the policy may already have been created. Check the policy list first. Rotating a key does not reset its current quota.

Rotate a key

  1. Find the key in the Active list and select Rotate.
  2. Review the confirmation dialog: rotating issues a new secret and shows it once, and the current secret stops working immediately. Cancel to keep the current secret.
  3. Confirm. The new secret appears in the same green banner as a newly created key. Copy it into your script’s secret store before leaving the screen.

Rotation is how you replace a leaked or expiring secret. The key keeps its identifier, name, allowed operations, expiry, hourly limit and both usage counters, so only the secret in your script changes. Only a key in the Active list can be rotated; revoked and expired rows have no Rotate action.

Revoke a key

  1. Find the key in the Active list and select Revoke.
  2. Review the confirmation dialog and confirm the revocation, or cancel to keep the key.
  3. The key remains in history under Revoked. New admissions are blocked immediately; an operation admitted before revocation may still finish.

Use a new key and update the consuming script when access is needed again. Revocation does not reactivate old secrets.