Table of contents

API Keys

API Keys allow you to write applications that interact with the GrayMeta Platform. Normally, you’ll use the GrayMeta Platform web application to manage keys, but you may also manage them via the API Keys API.

API keys inherit the permissions of the user who created it.

Using a key

To use an API key in a request to GrayMeta Platform, set the Authorization header:

Authorization: Bearer {KEY}
  • {KEY} The API key

Creating a key

To create a key, make the following request:

POST /api/data/api-keys
{
	"name": "Name of key"
}
  • name - (optional) A human readable label for the API key (e.g. Slack Integration)

If no name is specified, a default one will be provided.

The response will look like this:

{
	"id": "abc123",
	"jwt": "APIKEY",
	"active": true,
	"user_id": "591481bf1940f20c341b9386a9a192f4",
	"created_at": "2017-05-31T20:56:04.002433Z",
	"updated_at": "2017-05-31T20:56:04.002433Z"
}
  • id - (string) The internal ID of the key (this is not the key itself, but how you refer to the key)
  • jwt - (string) The JWT API Key that should be used in the Authorization header
  • active - (bool) Whether the key is active or not
  • user_id - (string) The ID of the user who owns this key
  • created_at - (datetime) When the key was created
  • updated_at - (datetime) When the key was last updated

Updating the name of a key

API keys have names so that users can remember which key is used in each context, and names may be changed or updated:

PUT /api/data/api-keys/{key-id}
{
	"name": "New name"
}
  • key-id - (string) The API Key ID (not the JWT itself)
  • name - (string) The name of the key

Listing all keys for a user

To list all the keys that exist for a specific user, make the following request:

GET /api/data/api-keys

The response will list every available key:

{
	"api-keys": [
		{
			"id": "abc123",
			"jwt": "APIKEY",
			"active": true,
			"user_id": "591481bf1940f20c341b9386a9a192f4",
			"created_at": "2017-05-31T20:56:04.002433Z",
			"updated_at": "2017-05-31T20:56:04.002433Z"
		},
		{
			"id": "abc124",
			"jwt": "APIKEY",
			"active": true,
			"user_id": "591481bf1940f20c341b9386a9a192f4",
			"created_at": "2017-05-31T20:56:04.002433Z",
			"updated_at": "2017-05-31T20:56:04.002433Z"
		},
		{
			"id": "abc125",
			"jwt": "APIKEY",
			"active": false,
			"user_id": "591481bf1940f20c341b9386a9a192f4",
			"created_at": "2017-05-31T20:56:04.002433Z",
			"updated_at": "2017-05-31T20:56:04.002433Z"
		}
	]
}

Revoking a key

When you are no longer using an API key, it is recommended that you revoke it:

DELETE /api/data/api-keys/{key-id}
  • key-id - (string) The API Key ID (not the JWT itself)

Future requests using that key will not work.

This documentation is generated from the latest version of GrayMeta Platform. For documentation relevant to your own deployed version, please use the documentation inside the application.