API Key authentication

API Keys are unique, named tokens with a role assignment that can be used to authenticate and interact with Diagrid Conductor. API Keys are useful for authenticating via the CLI to automate tasks without requiring a user to perform a login action explicitly.

Note

API keys can only be generated in Conductor Enterprise.

After creating an API key, you can authenticate requests to Conductor via the Diagrid CLI by including the value of the secret token as the --api-key argument. Providing this argument will bypass the current user's credentials and run the request based on the token permissions.

The secret token can be saved in a secure location on your device for continued use with the CLI. For instance, in a Unix-like environment, saving the token to the location /secure-folder/diagrid-secret-token allows you to run commands like the following.

conductor_api_key=$(cat /secure-folder/diagrid-secret-token)

diagrid clusters list --api-key "${conductor_api_key}"

Read the CLI reference documentation for more information on how to use an API key with any command in the Diagrid CLI.

Generate API key

In Conductor, API keys can be generated using the Diagrid CLI or the console using the steps outlined below.

Important

An API key secret token is only visible at create time, so make sure to copy the generated output.

Console

1. In the left sidebar of the Conductor console, navigate to the API Keys tab.
2. In the upper-right corner of the page, click the + Create API Key button.
3. Provide a unique name for the API key.
4. Select an expiration period or select never (not recommended).
5. Set role assignments for the API key. See User roles for more details.
6. In the lower-left corner, select Create to generate the API Key.
7. Copy the secret key and save in a secure place.

CLI

Create API Key with global role

A global role is specified using the format diagrid:<role> where <role> is admin, editor or viewer.

In this example, the API key has the global admin role and a 24h expiration time, specified in seconds.

info

If no expiration period is configured when an API key is generated, the value is set to never (not recommended).

diagrid apikeys create --name my-api-key --role diagrid:admin --duration 86400

{
  "name": "my-api-key",
  "token": "secret-token"
}

Create API key with scoped role

Scoped roles are specified using the format diagrid:<role>:clusters:<clusterIds> where <role> is is editor or viewer and <clusterIds> represents a comma-separated list of 1+ cluster Id(s).

In this example, the API key has editor permissions on a specific cluster with id <clusterId> and a 30 day expiration, specified in seconds.

# Obtain desired <clusterId>
diagrid clusters list

diagrid apikeys create --name my-api-key --role diagrid:editor:clusters:<clusterId> --duration 2592000

{
  "name": "my-api-key",
  "token": "secret-token"
}

Delete API Key

To revoke access from non-expiring API keys or to clean up expired API keys, you are required to manually delete them.

Console

1. In the left sidebar of the Conductor console, navigate to the API Keys tab.
2. Navigate to the key you want to delete.
3. Select the action menu represented by three vertical dots and select Delete API Key.
4. Select confirm.

CLI

Use the Diagrid CLI to delete an API key by first obtaining the API key id from the output of the diagrid apikeys list command.

# Obtain desired <my-api-key-id>
diagrid apikeys list

diagrid apikeys delete <my-api-key-id>