API Keys
The API Keys pages (routes /api-key-overview and /api-key-new) manage the credentials that automated clients use to access resources or the Agilicus API without an interactive login.
Purpose
An API key is a credential used to access resources or the Agilicus API without needing an explicit login. Use API keys when the client supports basic (username and password) authentication but not an OpenID Connect login, or when you need to run a process unattended and cannot use a service account. Treat an API key like a password: when using it, the username is the identity (the email address) of the user to whom the key belongs, and the password is the secret value returned when the key was created.
Why use it
- Authenticate scripts, integrations, and command-line tooling (see API and automation).
- Mount shares and access resources from clients that only support basic authentication.
- Give each automated client a named, revocable credential with a defined set of scopes and an expiry.
- Review and revoke keys you no longer use.
When to use it
- When a tool supports basic authentication but not a full single sign-on login.
- When you need unattended access and a service account is not appropriate.
- When a legacy client needs to reach a resource or API.
Prerequisite: permission to administer API keys (an owner or administrator role).
How to use it
Overview
- Open Access > API Keys > Overview from the left navigation.
- Review the table. Each row shows the User the key belongs to, the key Name, its Scopes, and its Expiry date. The Key Status filter can hide expired keys.
- To revoke keys, tick the rows and select DELETE API KEYS. To create a key, select ADD API KEY, which takes you to the New API Key wizard.
Creating an API key
- API key name: give the key a name that tells you what it is for.
- Choose API Key for: select Self (the signed-in user’s identity) or Service Account.
- Scopes: choose API Scope or Resource Scope, then add scopes with ADD SCOPE and the scope table.
Type a scope such as urn:agilicus:app:erx:* into the new row and click away to add it as a chip.
- Expiry Date: choose when the key expires. This is required.
- Apply: review the summary, then select APPLY.
- Done: the wizard shows the key once, with the Username and Password (the secret) and copy buttons.
Copy and store the secret now: the message warns that the key will not be retrievable later.
Fields and controls reference
| Control | Purpose | Required | Default | Valid values | Notes |
|---|---|---|---|---|---|
| User | The identity the key belongs to | Read-only | n/a | n/a | |
| Name | The key’s name | Yes | n/a | Any text | Shown in the overview list |
| Scopes | What the key may access | Yes | n/a | Scope URNs such as urn:agilicus:app:erx:* | Freeform chip entries |
| Expiry date | When the key stops working | Yes | n/a | A date | Required for creation |
| API Scope / Resource Scope | The kind of scopes to add | No | n/a | API or resource scopes | |
| ADD API KEY | Opens the creation wizard | n/a | n/a | n/a | |
| DELETE API KEYS | Deletes the selected keys | n/a | n/a | n/a | Revocation is permanent |
| Key Status | Filters the list | No | Hide expired keys | Hide expired keys | Clear to show expired keys |
Dialogs and popups
- Confirmation dialogs: deleting API keys confirms before acting. The secret shown at the end of the wizard appears only once; there is no dialog to recover it later.
Configuration versus diagnostics versus confirmation
- Configuration: key names, scopes, and expiry dates.
- Diagnostics: the overview list shows each key’s user, scopes, and expiry; expired keys are identifiable and can be filtered.
- Confirmation: deleting a key immediately breaks anything using it. The secret shown at creation is shown once only, so save it before continuing.
Pagination and async behaviour
- The overview table pages at 25 rows per page. Expired keys are hidden by default; clear the Key Status filter to see them.
- Key creation applies asynchronously; the wizard advances only after the key is created. After deleting keys, wait a few seconds and reload to confirm.
Troubleshooting
- A client cannot authenticate: confirm the key has not expired and still exists in the overview. Check the scopes cover the resources being accessed. The username is the identity email, and the password is the secret shown at creation; it cannot be recovered.
- The key is not in the overview: expired keys are hidden by the default filter. Clear Key Status to show them.
- I need to revoke a key: tick the row in the overview and select DELETE API KEYS. Deleting also ends any sessions using the key.