API key

This section describes how to authenticate a workload to Conjur Cloud using an API key.

An API key is an alphanumeric string with length of 51 to 56 characters. If you want your workload to authenticate to Conjur Cloud using an API key, you specify this when creating your workload. When the workload is created, the API key is generated randomly by Conjur Cloud. The API key can be manually rotated at any time. For details, see Rotate an API key.

Application credentials

A workload (host) authenticates to Conjur Cloud using the following credentials:

Credential Description
Login name

The literal value host/ followed by the fully qualified host id.

A fully qualified id is the entire policy namespace that describes where the host is declared in the hierarchy of policy branches. For example, hosts declared in a policy branch named data/aws have a fully qualified id of data/aws/my-host and the login name for that host is host/data/aws/my-host.

In an API request, the "/" characters must be encoded as %2F, so the example host name above would be encoded as host%2Fdata%2Faws%2Fmy-host.


The host's current API key.

An administrative user who has the appropriate permissions on the host resource can reset (rotate) the API key if it is lost or compromised. Authenticated users with appropriate permission can get the current API value of a host using the API or CLI.

The API key is a randomly generated secret assigned by Conjur Cloud when the host is created. When you load policy that creates a host, the output from the load command includes the API key for each host that was created. Here is partial command output from a policy load that created two hosts:

"conjur:host:data:frontend/frontend-01": "33f0ppq25sy3kx1qx630b2mvth2126nscms28bk7qy3hrw
"conjur:host:data:frontend/frontend-02": "2w7dkpv2eszx6nvgvgvy2q2z5seq6n3gk33z1fem3z7f64

A host needs access to its credentials to authenticate to Conjur Cloud and get access to secrets. Credentials are typically located in files or in environment variables.

  • For workloads that are long-running, such as servers and VMs, the typical way to store the credentials is in a file accessible to the application. For example: /etc/conjur.identity.

  • For workloads that can accept configuration through the environment, such as Docker containers, CI jobs, and Heroku applications, the environment variables CONJUR_AUTHN_LOGIN and CONJUR_AUTHN_API_KEY are used.

  • For short-lived applications, such as some containers or temporary VMs, Host Factory tooling or Conjur Cloud integrations are used to manage identity.

Rotate an API key

If your workload has an API key, you can rotate the key from the Resources page, or using the Conjur Cloud CLI or API.

  1. On the Resources page, select the workload whose API key you want to rotate.

  2. Select More Options () > Rotate API key:

  3. Click Rotate.

  4. Important: Copy the new API key. You will not be able to access it after closing the dialog.

  5. Replace the old API key with the new API key where required.