API Keys

Create API keys for scripts and integrations, with access per module or for all modules.

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.

What a key can reach

A key reaches the modules of Aegis through the API: risks, policies, procedures, vendors, evidence, controls and frameworks, incidents, GDPR registers, DORA, the EU AI Act, reports, workflows, analytics, the dashboard, audit log, audit readiness, environmental metrics, the Trust Center (read only) and more. Settings › API Keys lists the modules a key can reach today. The API reference marks each operation a key may call with its level (x-api-key-level) and module (x-api-key-module).

Some operations never accept a key, whatever its access: data subject requests and data-subject lookups, creating or changing incidents (a data breach starts a legal deadline), deleting, approving or rejecting evidence, EU AI Act conformity attestations, Declarations of Conformity, FRIA submissions, classifications and transparency notices, creating, changing, importing or running workflows, creating or changing scheduled reports, the peer-benchmarking consent, whistleblower identity, user and role management, API key management, single sign-on and identity-provider settings, AI provider settings, tenant licence settings, licence and billing.

Choose the access

• All modules: Read or Read/Write in every module the API reaches.
• Per module: choose No access, Read or Read/Write for each module. A choice is greyed out when the API has no operation of that kind in the module.
• Admin: everything a Read/Write key can do, plus admin-only operations such as safe settings. An admin key needs at least one allowed IP address or range.

You can change the access later with Edit, without issuing a new secret. The same Edit API key dialog also changes the name, the allowed IP addresses, the expiry and the hourly limit. A key never exceeds its owner’s current permissions.

Create a key

1. Enter a descriptive Key Name, up to 100 characters.
2. Under Access, choose All modules, Per module or Admin.
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 IPv4 or IPv6 address or CIDR range per line, up to 32. Leave the field empty for no IP restriction; the form then warns No IP restriction: this key will work from any address. An entry that is not a valid address or range is refused before the key is created. 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.

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 with the address of the last call (From …), access, the allowed IP addresses (or Any IP address), expiry, admission count and hourly limit. After a rotation with overlap, the row also says when the previous secret stops working. 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 and choose its access. Existing names, scopes and historical counts remain visible; historical usage counts do not have the same meaning as current admission counts.

Review API activity

The screen has two tabs, Keys and API access. Open API access to see Recent API calls: the newest admitted calls and denied attempts, with Time, Key, Request, Outcome, Reason and Client IP. Filter by Key and by Outcome (Admitted or Denied). A denial names its reason in words, such as IP address not allowed, Access level too low for this operation or Hourly limit reached, so you can tell a misconfigured script from an attempt with a stolen secret. Entries are kept for 90 days.

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. Under Keep the previous secret working for, choose No overlap (stops immediately), 1 hour, 24 hours or 7 days — an overlap gives your scripts time to switch to the new secret. 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, access, 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.