API Keys

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

An API key (a secret that lets a script call Aegis without a person signing in) is how a CI pipeline, a reporting tool or an import script reads and writes compliance data. Each key acts on behalf of the administrator who created it, never with more rights than that person has today.

Who uses it

Admin Administrators can open Settings → API Keys (/settings/api-keys), create keys, edit them, rotate their secrets and revoke them. Other roles are redirected away from the page. 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.

When your licence does not include API access, the page shows a lock icon, the message This feature is not available on your current plan. Upgrade to enable this feature. and a View Plans button that opens the licence settings.

What’s on this screen

The access, IP and limit settings are described in the sections that follow. When no key has been created yet, the list reads No API keys created yet. Create your first API key above.

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. The Per module list under Access shows 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). Open it from the two links under the screen title: API reference: operations usable with API keys shows only those operations, Full API reference the whole API.

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.

The same rule also covers: the GRC Coach chat and management sign-offs, the decision that closes a questionnaire campaign, the AI transfer impact assessment for a GDPR transfer, data-loss investigations and the Microsoft Purview connector settings, the custom domain, publishing the Trust Center, approving a paused workflow run and its webhook secret, and managing MCP servers. These are decisions or settings a person makes, or actions that start a legal clock or reach outside Aegis. The create form repeats the short version under Access: Never available with any key: data subject requests, whistleblower identity, user and role management, API key management, and licence and billing.

Choose the access

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. With All modules, also pick Read (the default) or Read/Write; with Per module, a list of modules opens with a choice per module.
  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; in that state an admin key cannot be created at all.
  6. Select Create Key. The button reads Creating… while it works. The full secret then appears once in a green banner headed API key created successfully. Copy it now — it won't be shown again.
  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.

Create Key stays unavailable while the name is empty, while the access or IP entries have an error, and while a secret banner is still on screen, so an uncopied secret can never be replaced by a new one.

Save the secret before leaving

The full key cannot be recovered later. Aegis stores its hash and displays only a prefix afterwards. 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: a request that carries it is refused. 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. The Status filter also offers Revoked, Expired and All statuses; select All statuses to include revoked and expired history. When no key matches the filter, the list reads No API keys with this status.

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.

Column What it shows
Name The key name with an access badge (Read, Read/Write, Admin, Per module or Legacy scopes) and, for a per-module key, the modules it reaches.
Key The stored prefix only, never the full secret.
Created The creation date.
Last Used The time of the last admission (or Never), From … with the caller’s address, the admission count and Limit: … per UTC hour.
Status Active, Revoked or Expired, then the availability, Expires: … or No expiry, the allowed IPs or Any IP address, and any overlap notice.
Actions Edit, Rotate and Revoke, on active keys only.

Besides Available, the availability line can say that the owner is unavailable, that the owner no longer has the required permission, that the owner must set up two-factor authentication before the key can be used (or that this could not be checked, in which case the key is refused until it can), that the module is unavailable, or that IP restrictions are unavailable until an administrator verifies the ingress configuration.

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.

Edit a key

  1. Find the key in the Active list and select Edit. The Edit API key dialog opens with the key’s current settings filled in.
  2. Change the Key Name, the Access, the allowed IP addresses, the expiry or the hourly limit. The same checks as in the create form apply.
  3. Select Save to keep the changes, or Cancel to close the dialog. The secret stays the same, so the script that uses the key needs no change.

A key whose scopes predate access levels shows a note that some scopes cannot be displayed. They stay as they are unless you choose other access. While IP restrictions are unavailable, an existing IP list can still be cleared, but not filled.

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.

The tab shows up to the 100 newest entries for the chosen filters. The other denial reasons are Key expired, Key revoked, Key owner lacks the permission, Operation never available to API keys and Invalid credential. A Client IP of Unknown means the address could not be trusted. With no matching entries, the tab reads No API calls recorded for this filter.

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.

Request rate limits

Separately from a key's hourly limit, every API route has a per-minute limit counted per client IP address. It applies to API keys and to signed-in browsers alike, and everyone behind the same office network address shares it.

Applies to Limit
Most API routes, such as GET /api/evidence/{id}/file 100 requests per minute, counted separately for each route
Search and list routes 60 requests per minute, shared by all search and list routes
Policy and procedure document import 20 uploads per minute, shared by both import routes
AI features 5 to 30 requests per minute depending on the feature, mostly counted per user
Sign-in and other authentication routes 5 to 10 requests per minute

Requests for different records of one route — /api/evidence/A/file and /api/evidence/B/file — count against that one route. Over the limit, Aegis answers HTTP 429 with a JSON body {"error": "Too many requests", "retryAfter": 42} and these headers:

A script should wait for Retry-After before trying again rather than retrying at once, and should fetch files such as evidence downloads one after another rather than dozens in parallel.

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, headed API key rotated. Copy the new secret now — it won't be shown again. 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. Rotate is also unavailable while another secret banner is still on screen: copy and dismiss that secret first.

Revoke a key

  1. Find the key in the Active list and select Revoke.
  2. Review the Revoke API key dialog, which warns that the action cannot be undone, and confirm with Revoke, or select 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.

Tips and limits

Where this connects