Administration API keys
API keys
An API key lets a script read your workspace as one role, until the key expires. Use one for a script or a SIEM pull.
Who can do it
Creating, listing and revoking keys need Manage API keys (api_keys:manage), which the Owner and Admin roles hold. Without it the page says "You need permission to manage API keys." and draws nothing else.
A key acts as one role, and never above the person who created it. If the creator's own permissions shrink, the key shrinks with them. If the creator leaves the workspace, the key stops working. A key never carries Manage API keys, Manage members or Manage workspace settings, whatever its role, so a key cannot create more keys, change who is a member, or change settings.
Create a key
- Open Settings › Access › API keys and choose Create key.
- Enter a Name, up to 80 characters, so you can tell the key apart later.
- Choose a Role. A role with a permission you do not hold is shown disabled.
- Choose Expires after: 30 days, 90 days or 1 year. Every key expires.
- Choose Create key.
- In Copy your key, copy the key. The dialog says "This is the only time the key is shown. Store it now; we keep only its hash." Done stays disabled until you tick I have stored this. The dialog also gives a ready-made
curlcommand under Try it.
Use a key
Send the key in the Authorization header of each call:
The Try it command in the dialog is a complete example for your deployment. When a call carries an Authorization header, the key is the whole authentication; the session cookie is ignored.
A key can call only the routes in the public API reference. See Authentication. The reference groups them as Overview, Posture, Alerts, Issues, Activity, Inventory, Machines, Accounts, Policies and Usage. Two machine operations never take a key, because each makes a credential of another kind: issuing a removal key and issuing an elevation grant.
The list
| Column | What it shows |
|---|---|
| Name | The name you gave it. |
| Prefix | oxel_ and the first four characters. Hover for eight. |
| Role | The role it acts as. |
| Created by | The person who made it, or Deleted account. |
| Last used | When it was last used, or Never. |
| Expires | The date. Under seven days left it shows a badge such as "in 6 days". Revoked and Expired are shown as badges. |
The badge beside the title counts the keys that are active.
Revoke a key
Open the ⋯ menu on the row and choose Revoke…. The dialog says "Anything still using oxel_… is refused from now on. This cannot be undone." Only a key that is not yet expired or revoked has the menu.
Creating and revoking a key are written to the audit log, and so is the use of a key.
Every setting
| Setting | What it does | Default |
|---|---|---|
| Name | Labels the key. 1 to 80 characters. | Empty. The box shows "e.g. Splunk pull" as an example. |
| Role | The role the key acts as. | None chosen |
| Expires after | 30 days, 90 days or 1 year. | 90 days |
When it goes wrong
- A key's name must be 1 to 80 characters. Give it a name.
- That role has permissions you don't have. Choose a role you hold the permissions of.
- A key expires after 30, 90 or 365 days. Choose one of the three.
- Managing API keys requires api_keys:manage in this workspace. Ask an Owner or Admin.
- The key could not be created. / The key could not be revoked. / The API keys could not be read. The call failed; try again.
- From the API, a response with status 401 and code
unauthorized: the key is wrong, expired, revoked, or its creator is no longer in the workspace. - From the API, status 403 and code
api_key_route: "An API key cannot call this route. It is for a signed-in person in the console." Use a route from the API reference.
With the API
Not available with an API key. Keys are created and revoked in the console only. To use a key, start at Authentication.