REST API Authentication

Authentication Methods

Two REST API authentication methods are available:

• API keys

• Session tokens

The REST API Documentation area at the top of the REST API documentation page provides summary information about both authentication methods.

For detailed information specifically about API key authentication, read the following documentation.

About API Key Authentication

API key authentication requires each client to supply a key (token) to authenticate its requests to the Keep REST API. This feature is an alternative to traditional “username and password” authentication and is intended for use by any external system that integrates with Keep.

Keep application administrators can generate client-specific API keys for clients to use.

The REST API Documentation area at the top of the REST API documentation page provides an introduction to API key authentication.

What Is a Key?

A key is a unique string of numbers and letters, arranged into a prefix and a secret component, separated by a period:

[PREFIX].[SECRET]

The authenticated session that results from using a key to make a request lasts only for the lifetime of the request. So, when using API key authentication, there is no need to explicitly end sessions; they are automatically ended when Keep completes the REST API request.

Security

API keys are secrets in the same way as passwords. So, after they are generated, they should be stored securely and not shared. Do not store a generated key in a source control system alongside programming code.

For projects using keys, it is recommended that you supply keys via system properties or other external means of configuration.

Warning

Keep does not store API keys after it generates them. As a result, lost API keys cannot be recovered from Keep.

Key Creation and Management

API keys can be created and managed either through the Keep web application or through the api-keys resource of the REST API. Both methods provide operations for generating, listing, and revoking authentication keys.

The following information describes generating a key for a third-party system that will integrate with Keep through the REST API.

API Key Creation and Usage Advice

We recommend that you first create a user account to represent the integration that will be using the API key to perform operations in Keep. For example, you could create a user named transact-integration-user.

Note

Any attempt to use a key for a user who is not allowed to log in (for example, because their password has expired, or their account is disabled or locked) will fail.

So, you must ensure that:

• The “integration user” that you want to generate a key for has the appropriate Keep role assigned to it.

• The user account's password is set to never expire.

To generate a key, you must use an account that has permissions to generate keys. This account will “own” the generated keys.

Log in to Keep as this user, and then generate an API key. During the generation process, specify that the “run-as identity” for the key is the name of the “integration user”. Requests that use the generated key will be made under the identity of that “run as identity” user account.

When the key has been generated, use it in the DM-API-KEY header of REST API requests. When the request is made:

1. Keep will use the supplied key to authenticate the request.

2. Keep will create a session (that is intended to last for the lifetime of the request).

3. When the request is complete, Keep will end the session.

The following sections describe how to manage (create and revoke) API keys.

Manage API Keys Through the Keep Web Application

You can access API key management functions through the Keep web application.

Generate a Key

To generate an API key, follow these steps:

1. Log in to Keep as an administrator, then click User Management > API Keys in the admin menu.

   

2. On the API Keys page, click New API Key.

   

3. In the Generate New API Key window:

   1. Enter a descriptive Label for the API key.

      

   2. Select a Run As Identity. The username of the account you want to use as the run-as identity. Requests that use the generated key will be made under the "run as identity" user's identity.

   3. Click Confirm.

4. In the API Key Successfully Generated window, click Copy to copy the API key to the clipboard. Store this key securely, because when the window is closed, the displayed value will be lost and cannot be recovered.

   

List Keys

Generated keys are listed on the API Keys page. Each key is identified by the prefix identifier, which is the part before the "." (period) in the generated key.

Revoke a Key

To revoke a key, follow these steps:

1. Click Delete in the relevant row of the API Keys page.

2. In the Delete API Key window, click Confirm.

   

Keep removes the key and prevents any further usage of it.

Manage API Keys Through the REST API

The api-keys resource provides the operations for generating, listing and revoking authentication keys.

Generate a Key

Use the /api-keys (POST) endpoint to generate a key. In the API request's body, you can specify a label for the key.

A successful request will return the generated API key. This secret key is not stored in the system and must be stored securely; if it is lost, you must generate a new key.

Note

The format of an API key is [PREFIX].[SECRET]. Both elements are unique. The prefix can be used to identify a key and is specified when revoking a key.

Optional: You can specify runAsIdentity in this API request's body. Requests that use the generated key will be made under the "run as identity" user's identity. If you do not specify runAsIdentity, the owner and run-as identity will be automatically set to the user making the request. If you specify a run-as identity, ensure that a valid username within the system is chosen else the request will fail.

Click Execute. The response to the request will be shown.

List Keys

Use the /api-keys/{keyPrefix} (GET) endpoint to list a particular generated key. The details of the key (such as its owner, run-as identity, and label) are shown along with the prefix identifier.

Note

The secret component of the key is not included.

Revoke a Key

Use the /api-keys/{keyPrefix} (DELETE) endpoint to revoke a key. Specify the prefix of the key that you want to revoke, then click Execute.