API Keys

API Keys authenticate requests, and ensure the caller has the permissions required to perform the request. API Keys are associated with an Account, and requests made with them track that Account's activities. Access can be revoked by disabling the API Key, or reducing its permission set.

API Keys can be used to manage access for internal users as well as external, and third party users. We encourage you to take advantage of being able to manage data outside of your ecosystem, and require third party data processors to encrypt your data when you are not the one managing it.

To use an API Key, pass it as the Bearer token in the Header of a Request:

Authorization Header

Authorization: Bearer [API Key]

When a request is made, it is verified and the action is attributed to the Account associated with the API Key.

Creating API Keys

API Keys are created by providing an Account and a set of flags (entitlements) that describe what actions are available when using it. The following is a list of available flags:

Create an API Key

POST auth/apikey

Body

{
   "accountId": "Account-Name",
   "flags": [
      "*.*.*.*",
      "keyring.read",
      "keyring.delete",
      "keyring.BOD.encrypt",
      "keyring.Audit.decrypt"
   ]
}

flags is a list of names

An entitlement is granted by being present in the list. There is no way to write one down as denied, because there is no value to write — a name is either in the set or it is not.

Earlier versions accepted a {"keyring.read": true} object here. They are no longer accepted: POST auth/apikey declares flags as an array of strings and an object body is rejected with a 400 before the request reaches the server's handler.

If you are updating existing integrations, the mapping is mechanical — keep every name whose value was true and drop the rest. Do not keep a false entry "to be explicit". It did not mean what it looks like: a flag set to false used to grant the entitlement it named, and "*.*.*.*": false conferred the full override. That is the defect the list shape removes.

Flags

[ring-name] stands for a literal KeyRing name; * is a wildcard that matches any ring in that position. Entitlement matching compares token counts first, so keyring.read and keyring.*.read are different names and neither implies the other — see Two-token names before granting either.

Completeness of this table

Verified 2026-09-06 by enumerating every name the platform's Access builder can require and diffing it against the rows below. That sweep added keyring.*.read, keyring.*.delete, keyring.[ring-name].config.*, asset.read, asset.update, asset.delete, integration.read, integration.write, sso.read and sso.write, and corrected keyring.*.encrypt, whose description said "decrypt". Two rows had also been merged into one line by a missing row break, which hid keyring.[ring-name].config.write entirely.

Flag	Description
`account.create`	Allows an Account to be created
`account.read`	Allows an Account to be read
`account.write`	Allows an Account to be updated
`account.delete`	Allows Accounts to be deleted
`activity.read`	Allows the Activity feed to be read
`apikey.read`	Allows the user to read the API Key details.
`apikey.write`	Allows API Keys to be created
`keyring.create`	Allows KeyRing creation
`keyring.delete`	Allows KeyRing deletes
`keyring.[ring-name].delete`	Allows for the specified KeyRing to be deleted
`keyring.*.delete`	Allows the delete action on any single named KeyRing. Does not authorize `DELETE /keyrings` (delete all), which requires the two-token `keyring.delete`
`keyring.read`	Allows KeyRing reads
`keyring.[ring-name].read`	Allows KeyRing read on a specified KeyRing
`keyring.*.read`	Allows KeyRing read on any single named KeyRing, and is what makes rows visible in the KeyRing LIST. Does not by itself authorize `GET /keyrings`, which requires the two-token `keyring.read`
`keyring.[ring-name].decrypt`	Allows the decrypt action on a specified KeyRing
`keyring.*.decrypt`	Allows decrypt action on all KeyRings
`keyring.[ring-name].encrypt`	Allows the encrypt action on a specified KeyRing
`keyring.*.encrypt`	Allows the encrypt action on all KeyRings
`keyring.[ring-name].rotate`	Allows a Key rotate on a specified KeyRing
`keyring.*.rotate`	Allows Key rotate on all KeyRings
`keyring.[ring-name].config.read`	Allows the KeyRing configuration to be read on a specified KeyRing
`keyring.*.config.read`	Allows the KeyRing configuration to be read on all KeyRings
`keyring.[ring-name].config.write`	Allows the KeyRing configuration to be changed on a specified KeyRing
`keyring.*.config.write`	Allows the KeyRing configuration to be changed for all KeyRings
`keyring.[ring-name].config.*`	Allows all actions on the specified KeyRing's configuration
`keyring..config.`	Allows all actions on all KeyRing configurations
`keyring.[ring-name].hash.read`	Allows the encrypt hash to be inspected for the specified KeyRing
`keyring.*.hash.read`	Allows the encrypt hash to be inspected for all KeyRings
`keyring.[ring-name].keys.read`	Allows the keys to be read from the specified KeyRing
`keyring.*.keys.read`	Allows the keys to be read from all KeyRings
`asset.read`	Allows an Asset's anchors to be read (`GET /assets/{assetId}/anchors`)
`asset.delete`	Allows an Asset to be deleted
`asset.update`	Allows an Asset to be updated. Required in addition to an encrypt name when encrypting against an Asset
`user.password-reset`	Allows for the password-reset of a user
`user.read`	Allows the reading of User details
`user.write`	Allows for new users to be created within the platform
`integration.read`	Allows Integrations and their configuration to be read
`integration.write`	Allows Integrations to be created, updated and removed
`sso.read`	Allows SSO configuration to be read
`sso.write`	Allows SSO configuration to be created, updated and removed