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": {
      "*.*.*.*": true,
      "keyring.read": true,
      "keyring.delete": true,
      "keyring.BOD.encrypt": true,
      "keyring.Audit.decrypt": true
   }
}

Flags

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.read`	Allows KeyRing reads
`keyring.[ring-name].read`	Allows KeyRing read on a specified KeyRing
`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 decrypt 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.*.config.write`	Allows the KeyRing configuration to be changed for all KeyRings
`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
`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