Authenticate

Gets a short-lived access token, which is required in the header of most subsequent API requests. A client can obtain an access token by presenting a valid login name and API key.

The access token is used to communicate to the REST API that the bearer of the token has been authorized to access the API and perform specific actions specified by the scope that was granted during authorization.

The login must be URL encoded. For example, alice@devops must be encoded as alice%40devops.

For host authentication, the login is the host ID with the prefix host/. For example, the host webserver would log in as host/webserver, and would be encoded as host%2Fwebserver.

Access tokens expire after 8 minutes. You need to obtain a new token after it expires.

Example with curl

In the following example, a host with ID some/application authenticates to Conjur at https://eval.conjur.org where account is set to myorg and the API key is apiKeyGoesHere using the authn authenticator:

curl --header "Accept-Encoding: base64" --data apiKeyGoesHere https://eval.conjur.org/authn/myorg/host%2Fsome%2Fapplication/authenticate

URI

  
POST /{authenticator}/{account}/{login}/authenticate

URI Parameters

Parameter

Type

Mandatory

Description

authenticator

String

Yes

Authentication method

Example: authn

account

String

Yes

Organization account name.

Example: myorg

login

String

Yes

Login name of the client. For users, it’s the user id. For hosts, the login name is host/<host-id>

Example: alice

Example URI

  
POST /authn/myorg/alice/authenticate

Request

Header

 
Accept-Encoding: base64
 

To encode the access token, you need to include base64 as the encoding format in the Accept-Encoding header. If base64 is not included in the header, a raw token is returned using application/json as the content type.

Body

The request body is the API key. For example:

14m9cf91wfsesv1kkhevg12cdywm2wvqy6s8sk53z1ngtazp1t9tykc

Response

Code

Description

200

The response body is the access token

401

The request lacks valid authentication credentials

Response 200 example

Header

  
Content-Encoding: base64
Content-Type: text/plain

Body

  
eyJwcm90ZWN0ZWQiOiJleUpoYkdjaU9pSmpiMjVxZFhJdWIzSm5MM05zYjNOcGJHOHZkaklpTENKcmFXUWlPaUkyTXpka05HWTFZMlU1WVdJd05ESTVOR0ZpWkRNNFptTmhPV00zWW1Nek5qWTVaak16TWprNU5UUXdZamhsTm1ZeU5tRTBNVGM1T0RFeE1HSm1aRGcwSW4wPSIsInBheWxvYWQiOiJleUp6ZFdJaU9pSmhaRzFwYmlJc0ltbGhkQ0k2TVRVNU9EYzJPVFUwTUgwPSIsInNpZ25hdHVyZSI6Ik5ya25FQTc2MnoweC1GVmRRakZHZVRUbkJzeXFBdlBHSWEyZUxZV3IyYVVGZDU5dHk0aGMxSlRsVGptdmpGNWNtVDNMUnFGbDhYYzNwMDhabEhjbVc0cTdiVnFtM21odmZEdVNVaE13RzhKUk4yRFZQVHZKbkFiT1NPX0JGdWhKdmk2OGJEVGxZSFFmUF81WHY1VWtuWHlLUDR2dGNoSjloMHJuVXN0T0F1YWlkM0RyQW5RV1c2dDRaMzRQajJhT2JrTkZ1TlMxNDBsamNwZ1A1dHdfU19ISzB6d1dlSXF4cjh6eUpTbk5aNjJ1WlhZV25zU051WGZtSWdtVVo2cTJFeVZWWUJ1Zk5SZTNVUmFkU09OYjRIcnFyX21UaGctWHUzMjA2N1h3QmNWZ3lWQ0JrcWtybktuRW1vRzlMRWs2ZjdNQVpDX1BXZnA4NXQ1VFFhVm1iZFlqT2lDTW9GMFoxYkhyZGN2MC1LRnpNRGxHa0pCS1Jxb0xYYkFGakhjMCJ9
 

If you use the authn authenticator and have the Conjur CLI installed you can get a pre-formatted access token with:

conjur authn authenticate -H

How to use the access token

For API usage, the access token is ordinarily passed as an HTTP Authorization “Token” header.

  
Authorization: Token token="eyJkYX...Rhb="

The access token can be used for Conjur API access like this:

  
curl --cacert <certfile> \
     -H "Authorization: Token token=\"$response\"" \
     <url>
 

If you did not encode the access token by passing the Accept-Encoding header and you received a raw token, you must format the token before you use it, as follows:

Take the response from the authentication request and base64-encode it, stripping out newlines:

response=$(echo -n $response | base64 | tr -d '\r\n')