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.

Password

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
dmna86fh",
"conjur:host:data:frontend/frontend-02": "2w7dkpv2eszx6nvgvgvy2q2z5seq6n3gk33z1fem3z7f64
93dqtwhm"
}

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.