12.1How API keys work
Last updated
A key always acts as a person
Every API key belongs to one platform user, its owner. A key never has an identity of its own: everything done with it is recorded in the operations log under the owner's name, with the key's name alongside. When you create a key you decide who it belongs to — normally yourself.
This has three consequences you should keep in mind:
- A key can never do more than its owner. A key carries one of its owner's roles, and on every request its permissions are cut down to what the owner holds at that moment. If the owner later loses a permission, the key loses it too, immediately. If the owner's account is deactivated, the key stops working.
- A key can only reach a directory its owner can reach. A key is linked to at most one Active Directory connection. The link is honoured only while one of the owner's roles still reaches that connection.
- A key is a machine credential. It is supervised: depending on its supervision level, some of the directory changes it requests wait for a person to approve them. People working in the console are never held this way. Supervision is covered below and in detail in Chapter 10, Operation policies, attribute policies and agent supervision.
What a key consists of
| Setting | What it decides |
|---|---|
| Name | How you recognise the key, for example the workflow that uses it |
| Owner (Belongs to) | The person the key acts as |
| Role | Which of the owner's roles the key carries |
| Supervision | Which directory changes run straight away and which wait for approval |
| Skip the always-ask wait | Whether operations pinned to "always ask agents" may run unattended |
| Expires | The date after which the key stops working, or never |
| Allowed addresses | The IP addresses or ranges the key may be used from |
| Directory | The one Active Directory connection the key can act on, and its Client ID |
The key value itself starts with ak_live_. It is shown once, at the moment of creation. The platform stores only a one-way hash of it, plus the ak_live_ prefix and the last four characters so you can recognise it in lists. Nobody — not even a System Admin — can read the full key again later.
Who can do what
| Permission | Allows you to |
|---|---|
apikeys:read | Open the API Keys page, see your own keys and read a key's details |
apikeys:list | Open the API Keys page, switch the list to All Keys and view other people's keys |
apikeys:create | Create keys for yourself |
apikeys:create-for-user | Create keys that belong to another user |
apikeys:update | Open a key's settings page and change your own keys |
apikeys:revoke | Revoke your own keys |
apikeys:delete | Delete your own keys |
apikeys:binding:read | See which directory a key is linked to |
apikeys:binding:manage | Link your own key to a directory, change or remove the link |
operations:approve | Choose Act without asking and turn on Skip the always-ask wait |
Opening a key's settings page needs both apikeys:read and apikeys:update. Without apikeys:binding:read, the AD scope column shows Any server for every key, because the page cannot read the links.
Important: Only the owner of a key can change it, revoke it or change its directory link. No permission widens that. An administrator with apikeys:list can open somebody else's key and see how it is configured, but the page is shown read-only. Deleting is the exception: a person whose active role is System Admin can delete any key.Creating a key for an account that holds the System Admin role requires that your own active role is System Admin. A key can never carry the System Admin role itself.
Last updated
Thank you for your feedback.