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:

PATCH /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"
		}
	]
}

Temporarily disable a key

PATCH /api/data/api-keys/{key-id}
{
	"active": false
}

key-id - (string) The API Key ID (not the JWT itself)
active - (bool)

Requests using this key will not work until it has been re-enabled (set active to true).

Permanently delete 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.