API Keys are an alternate way to authenticate into the database REST API's. Developers may find it useful to have applications connect to the database using API keys instead of using their personal login credentials.

API keys are primarily of 2 types:

1. Master Key
2. DS Key

Master Key

The master key has same permissions as the root user and only a root user or another master key holder may create new master keys. The master key will have access to all data across all the datastores in the cluster.

DS Key

The datastore level key has all permissions limited to a datastore. It may not perform system wide operations such as managing nodes or creating master keys. However it can access all the data inside the datastore, create tables, drop tables and perform all operations specific to the datastore.

Create a Master Key

blobcity>create-master-key
BC.77494db6db484bdcb52641ae300881c2acf73fe48a72423d804670b483effe2f

{
  "q": "CREATE-MASTER-KEY"
}

{
  "ack": "1",
  "key": "BC.77494db6db484bdcb52641ae300881c2acf73fe48a72423d804670b483effe2f"
}

BC.77494db6db484bdcb52641ae300881c2acf73fe48a72423d804670b483effe2f is a new master API key automatically created by the database. Only the root user may use the command create-master-key.

Create a DS Key

blobcity>create-ds-key test
DS.93a421661d9146c4812cb4d688db12324064344d9da547c7a6837d783d4f935b

{
  "q": "CREATE-DS-KEY",
  "p": {
  	"ds": "test"
  }
}

{
  "ack": "1",
  "key": "DS.93a421661d9146c4812cb4d688db12324064344d9da547c7a6837d783d4f935b"
}

DS.93a421661d9146c4812cb4d688db12324064344d9da547c7a6837d783d4f935b is a new system generated key for the datastore test. The test datastore must be existent for the operation to succeed. Multiple DS level keys may be created for the same datastore.

The key holder may perform any datastore level operations on the database. The user may create tables, drop tables, insert data, read data, change replication types of tables etc. The key holder however does not have permission to execute any operations that are outside the scope of the datastore.

Viewing Created Keys

blobcity>list-api-keys
BC.77494db6db484bdcb52641ae300881c2acf73fe48a72423d804670b483effe2f
DS.93a421661d9146c4812cb4d688db12324064344d9da547c7a6837d783d4f935b

{
  "q": "LIST-API-KEYS"
}

{
  "ack": "1",
  "key": [
    "BC.77494db6db484bdcb52641ae300881c2acf73fe48a72423d804670b483effe2f",
    "DS.93a421661d9146c4812cb4d688db12324064344d9da547c7a6837d783d4f935b"
    ]
}

The list-api-keys command displays all active keys. Only the root user or master key holder may execute this command. The command responds back with all master keys and DS level keys.

blobcity>list-ds-api-keys test
DS.93a421661d9146c4812cb4d688db12324064344d9da547c7a6837d783d4f935b

{
  "q": "LIST-DS-API-KEYS",
  "p": {
    "ds": "test"
  }
}

{
  "ack": "1",
  "key": [
    "DS.93a421661d9146c4812cb4d688db12324064344d9da547c7a6837d783d4f935b"
    ]
}

Alternately the list-ds-api-keys command can be used to view all active keys associated with a specific datastore. The datastore name must be specified to retrieve the datastore specific keys. Any root user, master key holder may execute this command. A holder of a key to the same datastore may also execute the command.

👍

Security Advisory

If a user has a DS level key for datastore my_ds then he will only have permission to execute list-ds-api-keys my_ds and will be able to view all api keys associated with my_ds. However if the user attempts list-ds-api-keys test or list-api-keys, the system will respond with an authorisation failure.

Dropping a Key

blobcity>drop-api-key BC.77494db6db484bdcb52641ae300881c2acf73fe48a72423d804670b483effe2f
API key successfully dropped

{
  "q": "DROP-API-KEY",
  "p": {
    "key": "BC.77494db6db484bdcb52641ae300881c2acf73fe48a72423d804670b483effe2f"
  }
}

{
  "ack": "1"
}

The drop-api-key command is used to drop an existing api key. Any programs using the key will no longer be able to use the api with the dropped key.

The root user may drop any of the keys. A master key can only be dropped by a master key holder and a datastore key maybe dropped by the same datastore key holder.

🚧

Key holders may not drop themselves

To drop an api key, the user must connect as a root user or with another key other than the key being dropped. The key executing the command may not itself be dropped. This prevents a user from locking himself out of the system.