Authenticate with REST APIs

The REST API accepts the following three forms of authentication:

  • Password

  • API key

  • Access token

The format requirements for each authentication method are described in the following sections.

Password and API key

Both of these authentication methods are provided using the HTTP basic authentication form of the authentication header. This is constructed as follows:

  1. Create the authentication string by concatenating the role's name, a literal colon character ":" and password or API key.

  2. Base64 encode the resulting authentication string.

  3. Prefix the authentication string with the scheme: Basic (note the required space).

  4. Provide the result as the value of the Authentication HTTP header.

Authentication: Basic ZGFuaWVsOjlwOG5mc2RhZmJw

Access token

Access tokens obtained via the Authenticate API can be presented using the Authentication header as follows:

  1. Create the authentication string by prepending a literal token= to the base64-encoded access token.

  2. Prefix the authentication string the scheme: Token (note the required space).

  3. Present the result as the value of the Authentication HTTP header.

Alternatively, the Conjur CLI can be used to both fetch an access token from the API and format the authorization header using the following command: conjur authn authenticate -H. The -H option instructs the CLI to return the access token formatted as an HTTP authorization to be easily used in other CLIs, such as curl. Refer to the example below:

curl -H "$(conjur authn authenticate -H)" [URL]

Access tokens expire after 8 minutes. You need to obtain a new token after it expires. Token expiration and renewal is handled automatically by the Conjur client libraries.

SSL verification

If you self-host Conjur, use the public key certificate you obtained when running conjur init for SSL verification when talking to your Conjur endpoint. This certificate is not a secret, so you can check it into source control if needed.

For example, with curl you can use the cert like so:

$ curl --cacert <certfile> ...