API Keys

API Keys help you manage access to your KeyRings

After creating a KeyRing, you'll want to provide access to it through your workflows or automated processes. This is where an API Key comes in. API Keys contain a set of flags, entitlements, that grant a caller permission to use a KeyRing. When creating an API Key, you'll provide a set of flags that will govern what actions the API Key has access to. Once created, the API Key can then be used as the Bearer token in an HTTP request. If the API Key does not have the permission to perform an action, a 401 Unauthorized will be returned.

Available Flags

FlagDescription
keyring.createAllows KeyRing creation
keyring.deleteAllows KeyRing deletes
keyring.readAllows KeyRing reads
keyring.<ring-name>.readAllows KeyRing read on a specified KeyRing
keyring.<ring-name>.decryptAllows the decrypt action on a specified KeyRing
keyring.<ring-name>.encryptAllows the encrypt action on a specified KeyRing
keyring.<keyring-name>.rotateAllows a Key rotate on a specified KeyRing
keyring.<ring-name>.config.readAllows the KeyRing configuration to be read on a specified KeyRing
keyring.<ring-name>.config.writeAllows the KeyRing configuration to be changed on a specified KeyRing

Creating an API Key

Create an API Key by making. POST request to https://api.grapheene.com/apikey. The body consists of:

PropertyRequiredDefaultDescription
flagstrueA string array representing the list of entitlements this API Key has
propsfalseMetadata that helps support integrating into workflows.

The response returns the details of an API Key:

{
  "key": "apikey-2d9c3f1e-de23-4923-9ee6-c7bb2f157afe",
  "keyid": "apikeyid-76f88f41-d95b-4dd8-9601-d57aef3c68b7",
  "createdAt": "2023-12-06T06:52:45.657Z",
  "active": true,
  "flags": {
    "keyring.comms.encrypt": true,
    "keyring.comms.decrypt": true,
    "keyring.comms.read": true,
    "keyring.comms.rotate": true
  },
  "props": {
	}
}
  • key: The API Key. This is the only time the API Key is ever provided. The platform saves API Keys as SHA512 hashes.
  • keyid: The API Key ID that references an aPI Key. This is used in place of an API Key when needing to manage an API Key without having access to the API Key itself. Modifications to the referenced API Key can only be made if the requestor has the proper flags to manage the referenced API Key.
  • createdAt: API Key creation timestamp in ISO-8601 format
  • active: If true, the API Key can be used, otherwise the API Key is disabled.
  • flags: The set of entitlements on the API Key.
  • props: Metadata attached to the API Key.