Conjur API

This is official documentation of the Conjur API. It allows you tremendous flexibility to control and manipulate your Conjur software.

Authentication

Most API calls require an authentication access token in the header. Here’s how to obtain it if you’re a human user:

  1. Use a username and password to obtain an API key (refresh token) with the Authentication > Login method.

  2. Use the API key to obtain an access token with the Authentication > Authenticate method.

If you’re a machine, your API key will be provided by your operator.

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> ...

Login

Login
GET/authn/{account}/login

Gets the API key of a user given the username and password via HTTP Basic Authentication.

Passwords are stored in the Conjur database using bcrypt with a work factor of 12. Therefore, login is a fairly expensive operation. However, once the API key is obtained, it may be used to inexpensively obtain access tokens by calling the Authenticate method. An access token is required to use most other parts of the Conjur API.

Your HTTP/REST client probably provides HTTP basic authentication support. For example, curl and all of the Conjur client libraries provide this.

Note that machine roles (Hosts) do not have passwords and do not need to login.

Example with curl

Suppose your account is “myorg” and you want to get the API key for user “alice” whose password is “beep-boop”:

curl --user alice:beep-boop \
     https://eval.conjur.org/authn/myorg/login

Headers

Field Description Example
Authorization HTTP Basic Auth Basic YWxpY2U6c2VjcmV0

Response

Code Description
200 The response body is the API key
401 The credentials were not accepted

Example URI

GET /authn/myorg/login
URI Parameters
HideShow
account
string (required) Example: myorg

organization account name

Request
HideShow
Headers
Authorization: Basic YWxpY2U6c2VjcmV0
Response  200
HideShow
Headers
Content-Type: text/html; charset=utf-8
Body
14m9cf91wfsesv1kkhevg12cdywm2wvqy6s8sk53z1ngtazp1t9tykc

Authenticate

Authenticate
POST/authn/{account}/{login}/authenticate

Gets a short-lived access token, which can be used to authenticate requests to (most of) the rest of the Conjur API. A client can obtain an access token by presenting a valid login name and API key.

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

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

Therefore, before the access token can be used to make subsequent calls to the API, a raw token must be formatted. Take the response from this method and base64-encode it, stripping out newlines.

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

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

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

NOTE: If you have the Conjur CLI installed you can get a pre-formatted access token with:

conjur authn authenticate -H

Request Body

The request body is the API key. For example: 14m9cf91wfsesv1kkhevg12cdywm.

Response

Code Description
200 The response body is the access token
401 The request lacks valid authentication credentials

Example URI

POST /authn/myorg/alice/authenticate
URI Parameters
HideShow
account
string (required) Example: myorg

organization account name

login
string (required) Example: alice

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

Request
HideShow
Headers
Content-Type: text/plain
Body
14m9cf91wfsesv1kkhevg12cdywm2wvqy6s8sk53z1ngtazp1t9tykc
Response  200
HideShow
Body
{
  "protected": "eyJhbGciOiJjb25qdXIub3JnL3Nsb3NpbG8vdjIiLCJraWQiOiI0NGIwMjBmNjY0MDBmNzFhZDQ3Y2I0N2IzYTFiNmU5MSJ9",
  "payload": "eyJzdWIiOiJhbGljZSIsImlhdCI6MTUwNTgzMDY1MX0=",
  "signature": "iRLTwNomb_b6TS4e539IIC-isPsc0kIn-F_ajlvnGdrN6brEEHnVha2vm0oDwOjpnmpFrMYLzn8aPo4_7DP3edssfQbpMG6OZI2Ea9DRfkhQGtSQ2fQvhDos_f16EX_jWQkYlsY6T_RurAxf_7VC4hEhjZA8nLkXOohA1DheyoJiT2-7vdpLmf42G7r1gPWHd_JuFkee28Ax2vCi35l4yQXkAHFaLkb3cAD2iwYuavv3qcFnYsT5WhLQqndPoNzgNa4dMvWRkVNUoVmvL30oE6lAlWPO4rFbPpmLwJRJFudDF8IVV9cVRKnV3z79_3RfEsHJ6YTHVX4Cv--cXmkT17QSFp87DK94DAOX3jKvJNo49DdqkzXqAPUIj3CD3IWI"
}

Change your password

Change your password
PUT/authn/{account}/password

Changes a user’s password. You must provide the login name and current password or API key of the user whose password is to be updated in an HTTP Basic Authentication header. Also replaces the user’s API key with a new securely generated random value. You can fetch the new API key by using Login.

Your HTTP/REST client probably provides HTTP basic authentication support. For example, curl and all of the Conjur client libraries provide this.

Note that machine roles (Hosts) do not have passwords. They authenticate using their API keys, while passwords are only used by human users.

Example with curl

Change the password of user alice from “beep-boop” to “EXTERMINATE”:

curl --verbose \
     --request PUT --data EXTERMINATE \
     --user alice:beep-boop \
     https://eval.conjur.org/authn/myorg/password

Now you can verify it worked by running the same command again, which should fail, because the password has changed. If you feel like a round-trip you can swap the passwords to change it back:

curl --verbose \
     --request PUT --data beep-boop \
     --user alice:EXTERMINATE \
     https://eval.conjur.org/authn/myorg/password

Headers

Field Description Example
Authorization Conjur access token Token token=“eyJkYX…Rhb=”

Request Body

The new password, in the example “supersecret”.

Response

Code Description
204 The password has been changed
401 The request lacks valid authentication credentials
404 User not found
422 A request parameter was missing or invalid

Example URI

PUT /authn/myorg/password
URI Parameters
HideShow
account
string (required) Example: myorg

organization account name

Request
HideShow
Headers
Content-Type: text/plain
Authorization: Basic Ym9iOjlwOG5mc2RhZmJw
Body
supersecret
Response  204

Rotate an API key

Replaces the API key of a role with a new, securely random API key. The new API key is returned as the response body.

Rotate your own API key
PUT/authn/{account}/api_key

Any role can rotate its own API key. The name and password or current API key of the role must be provided via HTTP Basic Authorization.

Your HTTP/REST client probably provides HTTP basic authentication support. For example, curl and all of the Conjur client libraries provide this.

Note that the body of the request must be the empty string.

Example with curl

Suppose your account is “myorg”, you are the user “alice”, your password is “beep-boop”, and you want to rotate your API key.

curl --request PUT --data "" \
     --user alice:beep-boop \
     https://eval.conjur.org/authn/myorg/api_key

Headers

Field Description Example
Authorization HTTP Basic Auth Basic ZGFuaWVsOjlwOG5mc2RhZmJw

Response

Code Description
200 The response body is the API key
401 The request lacks valid authentication credentials

Example URI

PUT /authn/myorg/api_key
URI Parameters
HideShow
account
string (required) Example: myorg

organization account name

Request
HideShow
Headers
Authorization: Basic ZGFuaWVsOjlwOG5mc2RhZmJw
Response  200
HideShow
Headers
Content-Type: text/html; charset=utf-8
Body
14m9cf91wfsesv1kkhevg12cdywm2wvqy6s8sk53z1ngtazp1t9tykc

Rotate another role's API key
PUT/authn/{account}/api_key?role={kind}:{identifier}

Rotates the API key of another role you can update.

Note that the body of the request must be the empty string.

Kinds of roles

Kind Description
User one unique wonderful human
Host a single logical machine (in the broad sense, not just physical)
Layer a collection of hosts that have the same privileges
Group a collection of users and groups that have the same privileges
Policy a role which owns of a set of related objects

Permissions required

update privilege on the role whose API key is being rotated.

Example with curl

Suppose your account is “myorg” and you want to rotate the API key for user “alice” whose current password is “beep-boop”:

curl --request PUT --data "" \
     -H "$(conjur authn authenticate -H)" \
     https://eval.conjur.org/authn/myorg/api_key?role=user:alice

Headers

Field Description Example
Authorization HTTP Basic Auth Basic ZGFuaWVsOjlwOG5mc2RhZmJw

Response

Code Description
200 The response body is the API key
401 The credentials were not accepted

Example URI

PUT /authn/myorg/api_key?role=user:alice
URI Parameters
HideShow
account
string (required) Example: myorg

organization account name

kind
string (required) Example: user

the kind of the role whose API key we will rotate, usually “user” or “host”

identifier
string (required) Example: alice

the id of the role

Request
HideShow
Headers
Authorization: Basic ZGFuaWVsOjlwOG5mc2RhZmJw
Response  200
HideShow
Headers
Content-Type: text/html; charset=utf-8
Body
14m9cf91wfsesv1kkhevg12cdywm2wvqy6s8sk53z1ngtazp1t9tykc

Secrets

A Variable is an access-controlled list of encrypted data values. The values in a Variable are colloquially known as “secrets”.

Only the twenty most recent values in a Variable are retained; this prevents the database from growing without bounds.

Add a secret

Add a secret
POST/secrets/{account}/{kind}/{identifier}

Creates a secret value within the specified Variable.

Note: Conjur will allow you to add a secret to any resource, but the best practice is to store and retrieve secret data only using Variable resources.

Example with curl

curl -H "$(conjur authn authenticate -H)" \
     --data "c3c60d3f266074" \
     https://eval.conjur.org/secrets/myorg/variable/prod/db/password

Request Body

Description Required Type Example
Secret data yes Binary c3c60d3f266074

Response

Code Description
201 The secret value was added successfully
401 The request lacks valid authentication credentials
403 The authenticated user lacks the necessary privilege
422 A request parameter was missing or invalid

Example URI

POST /secrets/myorg/variable/db/password
URI Parameters
HideShow
account
string (required) Example: myorg

organization account name

kind
string (required) Example: variable

should be “variable”

identifier
string (required) Example: db/password

id of the variable

Response  201
HideShow
Headers
Content-Type: application/xml

Retrieve a secret

Retrieve a secret
GET/secrets/{account}/{kind}/{identifier}{?version}

Fetches the value of a secret from the specified Variable. The latest version will be retrieved unless the version parameter is specified. The twenty most recent secret versions are retained.

The secret data is returned in the response body.

Note: Conjur will allow you to add a secret to any resource, but the best practice is to store and retrieve secret data only using Variable resources.

Example with curl

curl -H "$(conjur authn authenticate -H)" \
    https://eval.conjur.org/secrets/myorg/variable/prod/db/password

Response

Code Description
200 The secret values was retrieved successfully
401 The request lacks valid authentication credentials
403 The authenticated user lacks the necessary privilege
404 The variable does not exist, or it does not have any secret values
422 A request parameter was missing or invalid

Example URI

GET /secrets/myorg/variable/db/password?version=1
URI Parameters
HideShow
account
string (required) Example: myorg

organization account name

kind
string (required) Example: variable

should be “variable”

identifier
string (required) Example: db/password

id of the variable

version
integer (optional) Example: 1

version you want to retrieve (Conjur keeps the last 20 versions of a secret)

Response  200
HideShow
Headers
Content-Type: application/json
Body
c3c60d3f266074

Batch retrieval

Batch retrieval
GET/secrets{?variable_ids}

Fetches multiple secret values in one invocation. It’s faster to fetch secrets in batches than to fetch them one at a time.

Response

Code Description
200 All secret values were retrieved successfully
401 The request lacks valid authentication credentials
403 The authenticated user lacks the necessary privilege
404 At least one variable does not exist, or at least one variable does not have any secret values
422 A request parameter was missing or invalid

Example URI

GET /secrets?variable_ids=myorg:variable:secret1,myorg:variable:secret1
URI Parameters
HideShow
variable_ids
array (required) Example: myorg:variable:secret1,myorg:variable:secret1

Comma-delimited resource IDs of the variables.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "myorg:variable:secret1": "c3c60d3f266074",
  "myorg:variable:secret2": "d8dc3565123941"
}

Policies

Replace a policy

Replace a policy
PUT/policies/{account}/policy/{identifier}

Loads or replaces a Conjur policy document.

Any policy data which already exists on the server but is not explicitly specified in the new policy file will be deleted.

Size restriction

The body of this request (the policy to be appended) will be rejected by the server if it is larger than 10MiB.

Permissions required

update privilege on the policy.

Example with curl and jq

Suppose you have a policy to load in /tmp/policy.yml (such as the sample one provided below). The following command will load this as the “root” policy, replacing any other data that may already be in this policy:

curl -H "$(conjur authn authenticate -H)" \
     -X PUT -d "$(< /tmp/policy.yml)" \
     https://eval.conjur.org/policies/myorg/policy/root \
     | jq .

Request Body

The request body is a policy file. For example:

- !policy
  id: database
  body:
    - !host
      id: db-host
    - !variable
      id: db-password
      owner: !host db-host

Response

Code Description
201 The policy was loaded or replaced successfully
401 The request lacks valid authentication credentials
403 The authenticated user lacks the necessary privilege
404 The policy referred to a role or resource that does not exist in the specified account
422 The request body was empty or the policy was not valid YAML

Example URI

PUT /policies/myorg/policy/root
URI Parameters
HideShow
account
string (required) Example: myorg

organization account name

identifier
string (required) Example: root

id of the policy to load (root if no root policy has been loaded yet)

Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "created_roles": {
    "myorg:host:database/db-host": {
      "id": "myorg:host:database/db-host",
      "api_key": "309yzpa1n5kp932waxw6d37x4hew2x8ve8w11m8xn92acfy672m929en"
    }
  },
  "version": 1
}

Append to a policy

Append to a policy
POST/policies/{account}/policy/{identifier}

Adds data to the existing Conjur policy. Deletions are not allowed. Any policy objects that exist on the server but are omitted from the policy file will not be deleted and any explicit deletions in the policy file will result in an error.

Size restriction

The body of this request (the policy to be appended) will be rejected by the server if it is larger than 10MiB.

Permissions required

create privilege on the policy.

Example with curl and jq

Suppose you have a policy to load in /tmp/policy.yml (such as the sample one provided below). The following command will add data to the “root” policy:

curl -H "$(conjur authn authenticate -H)" \
     -X POST -d "$(< /tmp/policy.yml)" \
     https://eval.conjur.org/policies/myorg/policy/root \
     | jq .

Request Body

The request body should be a policy file. For example:

- !policy
  id: database
  body:
    - !host
      id: new-host
    - !variable
      id: new-variable
      owner: !host new-host

Response

Code Description
201 The policy was extended successfully
401 The request lacks valid authentication credentials
403 The authenticated user lacks the necessary privilege
404 The policy referred to a role or resource that does not exist in the specified account
422 The request body was empty or the policy was not valid YAML or the policy includes a deletion

Example URI

POST /policies/myorg/policy/root
URI Parameters
HideShow
account
string (required) Example: myorg

organization account name

identifier
string (required) Example: root

id of the policy to extend

Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "created_roles": {
    "cucumber:host:database/new-host": {
      "id": "cucumber:host:database/new-host",
      "api_key": "1n1k85r3pcs7av2mmpj233jajndc1bx8ma52rwybj31c487r72zree1c"
    }
  },
  "version": 2
}

Update a policy

Update a policy
PATCH/policies/{account}/policy/{identifier}

Modifies an existing Conjur policy. Data may be explicitly deleted using the !delete, !revoke, and !deny statements. Unlike “replace” mode, no data is ever implicitly deleted.

Size restriction

The body of this request (the policy to be appended) will be rejected by the server if it is larger than 10MiB.

Permissions required

update privilege on the policy.

Example with curl and jq

Suppose you have a policy to load in /tmp/policy.yml (such as the sample one provided below). The following command will create and delete data in the “root” policy:

curl -H "$(conjur authn authenticate -H)" \
     -X PATCH -d "$(< /tmp/policy.yml)" \
     https://eval.conjur.org/policies/myorg/policy/root \
     | jq .

Request Body

The request body should be a policy file. For example:

- !policy
  id: database
  body:
    - !host
      id: another-host
    - !delete
      record: !host new-host

Response

Code Description
201 The policy was updated successfully
401 The request lacks valid authentication credentials
403 The authenticated user lacks the necessary privilege
404 The policy referred to a role or resource that does not exist in the specified account
422 The request body was empty or the policy was not valid YAML

Example URI

PATCH /policies/myorg/policy/root
URI Parameters
HideShow
account
string (required) Example: myorg

organization account name

identifier
string (required) Example: root

id of the policy to update

Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "created_roles": {
    "cucumber:host:database/another-host": {
      "id": "cucumber:host:database/another-host",
      "api_key": "zcpanf1qj0be1spqmq51yfj69j24akjy413gsv501eqbf48136cw7v"
    }
  },
  "version": 3
}

Role-based access control

Show a role

Show a role
GET/roles/{account}/{kind}/{identifier}

Gets detailed information about a specific role, including the role members.

If a role A is granted to a role B, then role A is said to have role B as a member. These relationships are described in the “members” portion of the returned JSON.

Kinds of roles

Kind Description
User one unique wonderful human
Host a single logical machine (in the broad sense, not just physical)
Layer a collection of hosts that have the same privileges
Group a collection of users and groups that have the same privileges
Policy a role which owns of a set of related objects

Example using curl and jq

Suppose your account is “myorg” and you want to get information about the user “alice”:

curl -H "$(conjur authn authenticate -H)" \
     https://eval.conjur.org/roles/myorg/user/alice \
     | jq .

Headers

Field Description Example
Authorization Conjur access token Token token=“eyJkYX…Rhb=”

Response

Code Description
200 The response body contains the requested role
401 The request lacks valid authentication credentials
403 The authenticated user lacks the necessary privilege
404 The requested role does not exist

Supposing the requested role is a user named “otto” at an organization called “myorg”:

Example URI

GET /roles/myorg/user/otto
URI Parameters
HideShow
account
string (required) Example: myorg

organization account name

kind
string (required) Example: user

kind of role requested

identifier
string (required) Example: otto

identifier of the role

Request
HideShow
Headers
Authorization: Token token="eyJkYX...Rhb="
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "created_at": "2017-08-02T18:18:42.346+00:00",
  "id": "myorg:user:alice",
  "policy": "myorg:policy:root",
  "members": [
    {
      "admin_option": true,
      "ownership": true,
      "role": "myorg:user:alice",
      "member": "myorg:policy:root",
      "policy": "myorg:policy:root"
    }
  ]
}

List resources

List resources
GET/resources/{account}{?kind}{?search}{?limit}{?offset}{?count}

Lists resources within an organization account.

If a kind query parameter is given, narrows results to only resources of that kind.

If a limit is given, returns no more than that number of results. Providing an offset skips a number of resources before returning the rest. In addition, providing an offset will give limit a default value of 10 if none other is provided. These two parameters can be combined to page through results.

If the parameter count is true, returns only the number of items in the list.

If the search parameter is provided, narrows results to those pertaining to the search query. Search works across resource IDs and the values of annotations. It weights results so that those with matching id or a matching value of an annotation called name appear first, then those with another matching annotation value, and finally those with a matching kind.

Example with curl and jq

Suppose your organization name is “myorg” and you want to search for the first two resources matching the word “db”:

curl -H "$(conjur authn authenticate -H)" \
     'https://eval.conjur.org/resources/myorg?search=db&limit=2' \
     | jq .

Kinds of resources

Kind Description
User one unique wonderful human
Host a single logical machine (in the broad sense, not just physical)
Layer a collection of hosts that have the same privileges
Group a collection of users and groups that have the same privileges
Policy privileges on policies enable a user to create and modify objects and permissions
Variable a secret such as a password, API key, SSH key, etc
Webservice an HTTP(S) web service which performs sensitive operations

Request

Headers

Field Description Example
Authorization Conjur access token Token token=“eyJkYX…Rhb=”

Response

Code Description
200 Resources returned as a JSON list
401 The request lacks valid authentication credentials

Example URI

GET /resources/myorg?kind=variable?search=password?limit=2?offset=6?count=false
URI Parameters
HideShow
account
string (required) Example: myorg

organization account name

kind
string (optional) Example: variable

kind of object to list

search
string (optional) Example: password

search term used to narrow results

limit
number (optional) Example: 2

maximum number of results to return

offset
number (optional) Example: 6

number of results to skip

count
boolean (optional) Example: false

if true, return only the number of items in the list

Request
HideShow
Headers
Authorization: Token token="eyJkYX...Rhb="
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "created_at": "2017-07-25T06:30:38.768+00:00",
    "id": "myorg:variable:app-prod/db-password",
    "owner": "myorg:policy:app-prod",
    "policy": "myorg:policy:root",
    "permissions": [],
    "annotations": [],
    "secrets": [
      {
        "version": 1
      }
    ]
  },
  {
    "created_at": "2017-07-25T06:30:38.768+00:00",
    "id": "myorg:policy:app-prod",
    "owner": "myorg:user:admin",
    "policy": "myorg:policy:root",
    "permissions": [],
    "annotations": [],
    "policy_versions": []
  }
]

Show a resource

Show a resource
GET/resources/{account}/{kind}/{identifier}

The response to this method is a JSON document describing a single resource.

Permissions Required

read privilege on the resource.

Kinds of resources

Kind Description
User one unique wonderful human
Host a single logical machine (in the broad sense, not just physical)
Layer a collection of hosts that have the same privileges
Group a collection of users and groups that have the same privileges
Policy privileges on policies enable a user to create and modify objects and permissions
Variable a secret such as a password, API key, SSH key, etc
Webservice an HTTP(S) web service which performs sensitive operations

Example using curl and jq

curl -H "$(conjur authn authenticate -H)" \
    https://eval.conjur.org/resources/myorg/policy/app-prod \
    | jq .

Headers

Field Description Example
Authorization Conjur access token Token token=“eyJkYX…Rhb=”

Response

Code Description
200 Role memberships returned as a JSON list
401 The request lacks valid authentication credentials
403 The authenticated user lacks the necessary privilege
404 The requested resource does not exist

For example, to show the variable “db/password”:

Example URI

GET /resources/myorg/variable/db/password
URI Parameters
HideShow
account
string (required) Example: myorg

organization account name

kind
string (required) Example: variable

kind of resource requested

identifier
string (required) Example: db/password

the identifier of the resource

Request
HideShow
Headers
Authorization: Token token="eyJkYX...Rhb="
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "created_at": "2017-07-25T06:30:38.768+00:00",
    "id": "myorg:variable:db/password",
    "owner": "myorg:user:admin",
    "policy": "myorg:policy:root",
    "permissions": [],
    "annotations": [],
    "policy_versions": []
  }
]

Show permitted roles

Show permitted roles
GET/resources/{account}/{kind}/{id}?permitted_roles=true&privilege={privilege}

Lists the roles which have the named permission on a resource.

Kinds of resources

Kind Description
User one unique wonderful human
Host a single logical machine (in the broad sense, not just physical)
Layer a collection of hosts that have the same privileges
Group a collection of users and groups that have the same privileges
Policy privileges on policies enable a user to create and modify objects and permissions
Variable a secret such as a password, API key, SSH key, etc
Webservice an HTTP(S) web service which performs sensitive operations

Example with curl and jq

Suppose your organization name is “myorg” and you want to find out which roles have execute privileges on the Variable db-password, and can thus fetch the secret:

curl -H "$(conjur authn authenticate -H)" \
     'https://eval.conjur.org/resources/myorg/variable/db-password?permitted_roles=true&privilege=execute' \
     | jq .

Request

Headers

Field Description Example
Authorization Conjur access token Token token=“eyJkYX…Rhb=”

Response

Code Description
200 Permitted roles returned as a JSON list
401 The request lacks valid authentication credentials
403 The authenticated user lacks the necessary privilege
404 The specified resource does not exist
422 A request parameter was missing or invalid

Example URI

GET /resources/myorg/variable/db?permitted_roles=true&privilege=execute
URI Parameters
HideShow
account
string (required) Example: myorg

organization account name

kind
string (required) Example: variable

kind of resource requested

id
string (required) Example: db

password (string) - the identifier of the resource

privilege
string (required) Example: execute

roles permitted to exercise this privilege are shown

Request
HideShow
Headers
Authorization: Token token="eyJkYX...Rhb="
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  "myorg:policy:database",
  "myorg:user:db-admin",
  "myorg:host:database/db-host"
]

Check permission

Check permission
GET/resources/{account}/{kind}/{identifier}?check=true&role={role}&privilege={privilege}

Checks whether a role has a privilege on a resource. For example, is this Host authorized to execute (fetch the value of) this Secret?

Kinds of resources

Kind Description
User one unique wonderful human
Host a single logical machine (in the broad sense, not just physical)
Layer a collection of hosts that have the same privileges
Group a collection of users and groups that have the same privileges
Policy privileges on policies enable a user to create and modify objects and permissions
Variable a secret such as a password, API key, SSH key, etc
Webservice an HTTP(S) web service which performs sensitive operations

Example with curl

Suppose your account name is “myorg” and you want to check whether Host “application” can execute (fetch the value of) Variable “db-password”:

This request has a long URL, so I break it up for you with some variables.

endpoint='https://eval.conjur.org/resources'
account='myorg'
var_id='db-password'
host_id='application'

curl -i -H "$(conjur authn authenticate -H)" \
     '$endpoint/$account/variable/$var_id?check=true&role=$account:host:$host_id&privilege=execute'

Request

Headers

Field Description Example
Authorization Conjur access token Token token=“eyJkYX…Rhb=”

Response

Code Description
204 The role has the specified privilege on the resource
401 The request lacks valid authentication credentials
404 The role or resource was not found; or the role does not have the specified permission

Example URI

GET /resources/myorg/variable/db?check=true&role=myorg:host:application&privilege=execute
URI Parameters
HideShow
account
string (required) Example: myorg

organization account name

kind
string (required) Example: variable

kind of resource to test

identifier
string (required) Example: db

password (string) - the identifier of the resource to test

role
string (required) Example: myorg:host:application

the fully qualified identifier of the role to test

privilege
string (required) Example: execute

the privilege to test on the resource

Request
HideShow
Headers
Authorization: Token token="eyJkYX...Rhb="
Response  204

Host Factory

Create tokens

Create tokens
POST/host_factory_tokens

Creates one or more tokens which can be used to bootstrap host identity. Responds with a JSON document containing the tokens and their restrictions.

If the tokens are created with a CIDR restriction, Conjur will only accept them from the whitelisted IP ranges.

Permissions required

execute privilege on the Host Factory.

Example with curl and jq

Suppose your account is myorg, your host factory is called hf-db and you want to create two tokens, each of which which are usable only by local addresses 127.0.0.1 and 127.0.0.2, expiring at “2017-08-04T22:27:20+00:00”.

curl --request POST \
     --data-urlencode "expiration=2017-08-04T22:27:20+00:00" \
     --data-urlencode "host_factory=myorg:host_factory:hf-db" \
     --data-urlencode "count=2" \
     --data-urlencode "cidr[]=127.0.0.1" \
     --data-urlencode "cidr[]=127.0.0.2" \
     -H "$(conjur authn authenticate -H)" \
     https://eval.conjur.org/host_factory_tokens \
     | jq .

Note 1: curl will automatically encode your POST body if you use the --data-urlencode option. If your HTTP/REST client doesn’t support this feature, you can do it yourself.

Note 2: in this example, the two provided addresses are logical OR-ed together and apply to both tokens. If you wanted each token to have a different CIDR restriction, you would make two API calls each with count=1.


Request

Body Parameters

expiration
ISO 8601 datetime string (required) Example: 2017-08-04T22:27:20+00:00

Expiration date of the token

host_factory
string (required) Example: myorg:host_factory:hf-db

Fully qualified Host Factory id

count
integer (optional, default=1) Example: 2

Number of tokens to create

cidr
array (optional) Example: ["127.0.0.1","127.0.0.2"]

CIDR restriction(s) on token usage

Response

Code Description
200 Zero or more tokens were created and delivered in the response body
403 The authenticated user lacks the necessary privilege
404 Conjur did not find the specified Host Factory
422 A request parameter was missing or invalid

Example URI

POST /host_factory_tokens
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "expiration": "2017-08-04T22:27:20+00:00",
    "cidr": [
      "127.0.0.1/32",
      "127.0.0.2/32"
    ],
    "token": "281s2ag1g8s7gd2ezf6td3d619b52t9gaak3w8rj0p38124n384sq7x"
  },
  {
    "expiration": "2017-08-04T22:27:20+00:00",
    "cidr": [
      "127.0.0.1/32",
      "127.0.0.2/32"
    ],
    "token": "2c0vfj61pmah3efbgpcz2x9vzcy1ycskfkyqy0kgk1fv014880f4"
  }
]

Revoke tokens

Revoke tokens
DELETE/host_factory_tokens/{token}

Revokes a token, immediately disabling it.

Permissions required

update privilege on the Host Factory.

Example with curl

Suppose you have a Host Factory Token and want to revoke it:

token="1bcarsc2bqvsxt6cnd74xem8yf15gtma71vp23y315n0z201c1jza7"

curl -i --request DELETE \
     --header "$(conjur authn authenticate -H)" \
     https://eval.conjur.org/host_factory_tokens/$token

Request

Headers

Field Description Example
Authorization Conjur access token Token token=“eyJkYX…Rhb=”

Response

Code Description
204 The token was revoked
401 The request lacks valid authentication credentials
404 Conjur did not find the specified token

Example URI

DELETE /host_factory_tokens/1bcarsc2b…
URI Parameters
HideShow
token
string (required) Example: 1bcarsc2b…

the Host Factory Token to revoke

Response  204

Create a host

Create a host
POST/host_factories/hosts

Creates a Host using the Host Factory and returns a JSON description of it.

Requires a Host Factory Token, which can be created using the create tokens API. In practice, this token is usually provided automatically as part of Conjur integration with your host provisioning infrastructure.

Note: if the token was created with a CIDR restriction, you must make this API request from a whitelisted address.

Example with curl and jq

Supposing that you have a Host Factory Token and want to create a new Host called “brand-new-host”:

token="1bcarsc2bqvsxt6cnd74xem8yf15gtma71vp23y315n0z201c1jza7"

curl --request POST --data-urlencode id=brand-new-host \
     --header "Authorization: Token token=\"$token\"" \
     https://eval.conjur.org/host_factories/hosts \
     | jq .

Request

Headers

A Host Factory Token must be provided as part of an HTTP Authorization header. For example:

Authorization: Token token=2c0vfj61pmah3efbgpcz2x9vzcy1ycskfkyqy0kgk1fv014880f4

Body Parameters

id
string (required) Example: brand-new-host

Identifier of the Host to be created. It will be created within the account of the Host Factory.

annotations
object (optional) Example: {"puppet": "true", "description": "new db host"}

Annotations to apply to the new Host

Response

Code Description
201 A host was created, its definition is returned as a JSON document in the response body
401 The token was invalid, expired, or the CIDR restriction was not satisfied
422 The request body was empty or a parameter was not formatted correctly

Example URI

POST /host_factories/hosts
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "created_at": "2017-08-07T22:30:00.145+00:00",
  "id": "myorg:host:brand-new-host",
  "owner": "myorg:host_factory:hf-db",
  "permissions": [],
  "annotations": [],
  "api_key": "rq5bk73nwjnm52zdj87993ezmvx3m75k3whwxszekvmnwdqek0r"
}

Public Keys

Show public keys

Show public keys
GET/public_keys/{account}/{kind}/{identifier}

Shows all public keys for a resource as newline delimited string for compatibility with the authorized_keys SSH format.

Returns an empty string if the resource does not exist, to prevent attackers from determining whether a resource exists.

Kinds of resources

Kind Description
User one unique wonderful human
Host a single logical machine (in the broad sense, not just physical)
Layer a collection of hosts that have the same privileges
Group a collection of users and groups that have the same privileges
Policy privileges on policies enable a user to create and modify objects and permissions
Variable a secret such as a password, API key, SSH key, etc
Webservice an HTTP(S) web service which performs sensitive operations

Example using curl

curl https://eval.conjur.org/public_keys/myorg/user/alice

Response

Code Description
200 Public keys returned as newline delimited string

For example, to show all the public keys for the user “alice”:

Example URI

GET /public_keys/myorg/user/alice
URI Parameters
HideShow
account
string (required) Example: myorg

organization account name

kind
string (required) Example: user

kind of resource of which to show public keys

identifier
string (required) Example: alice

the identifier of the object

Response  200
HideShow
Headers
Content-Type: text/plain
Body
ssh-rsa AAAAB3Nzabc2 admin@alice.com

ssh-rsa AAAAB3Nza3nx alice@example.com