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
-
Header: the title
API Keys, the subtitleCreate and manage API keys for programmatic access to the Aegis API.and two links that open in a new tab:API reference: operations usable with API keysandFull API reference. -
Two tabs:
Keys(open by default) andAPI access. -
Create API Key (on the
Keystab): theKey Namefield (placeholdere.g., CI/CD Pipeline), theAccesschoice with its three options, two short notes on what no key can do and on the owner’s permissions, theExpiry (optional, local time)andAdmissions per UTC hour (1–10,000)fields side by side, theAllowed IP addresses and rangesbox and theCreate Keybutton. -
The key list below the form: the heading
API Keyswith aStatusfilter on the right, then a table with the columnsName,Key,Created,Last Used,StatusandActions. Each active row has three actions:Edit,RotateandRevoke.
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
-
All modules:
ReadorRead/Writein every module the API reaches, including operations that belong to no module and modules added later.Readreads whatever a Viewer can read;Read/Writeadds the writes a Contributor or Manager can make. -
Per module: choose
No access,ReadorRead/Writefor each module. A choice is greyed out when the API has no operation of that kind in the module. The key needs access to at least one module; until then the form showsGive the key access to at least one module. -
Admin: everything a
Read/Writekey 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
- Enter a descriptive
Key Name, up to 100 characters. -
Under
Access, chooseAll modules,Per moduleorAdmin. WithAll modules, also pickRead(the default) orRead/Write; withPer module, a list of modules opens with a choice per module. - Optionally choose an expiry using your local time. Leave it empty for no expiry.
-
Set
Admissions per UTC hourbetween 1 and 10,000. The default is 100. -
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. -
Select
Create Key. The button readsCreating…while it works. The full secret then appears once in a green banner headedAPI key created successfully. Copy it now — it won't be shown again. -
Select
Copy & Dismissand 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.
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
-
Find the key in the
Activelist and selectEdit. TheEdit API keydialog opens with the key’s current settings filled in. -
Change the
Key Name, theAccess, the allowed IP addresses, the expiry or the hourly limit. The same checks as in the create form apply. -
Select
Saveto keep the changes, orCancelto 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:
Retry-After— seconds to wait before the next request.X-RateLimit-Limit— the limit of this bucket.-
X-RateLimit-Remaining— requests left in the current window. -
X-RateLimit-Reset— when the window resets, in milliseconds since the Unix epoch.
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
-
Find the key in the
Activelist and selectRotate. -
Review the confirmation dialog: rotating issues a new secret and shows it
once. Under
Keep the previous secret working for, chooseNo overlap (stops immediately),1 hour,24 hoursor7 days— an overlap gives your scripts time to switch to the new secret. Cancel to keep the current secret. -
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
-
Find the key in the
Activelist and selectRevoke. -
Review the
Revoke API keydialog, which warns that the action cannot be undone, and confirm withRevoke, or selectCancelto keep the key. -
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
-
Give each script its own key with the narrowest access it needs.
Per modulewithReadis enough for most reporting tools. -
Add allowed IP addresses wherever your deployment supports them. The
API accesstab then shows a stolen secret used from elsewhere as a denied attempt. - A key stops working, without being revoked, when its owner leaves or loses the permission. Check the availability line in the list before you debug the script.
Where this connects
- API reference: every operation and its key level.
- Settings: licence and the other administration screens.
- Webhooks: for Aegis to call your systems instead.
- Audit log: key creation, rotation and revocation are audited.