REST APIs

We provide the following REST APIs to help integrate Conjur into your development environments. Click a link below to view documentation for each API.

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

The following APIs enable you manage Conjur authentication tasks:

API

Description

Login

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

Authenticate

Gets a short-lived access token, which can be used to authenticate requests to (most of) the rest of the Conjur API.

Change your password

Changes a user’s password.

Rotate Personal API Key

Replaces your own API key with a new, securely random API key.

Rotate Another Role's API Key

Replaces the API key of another role you can update with a new, securely random API key.

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.

The following APIs enable you to manage secret values within specified Variables.

API

Description

Add a Secret

Creates a secret value within the specified Variable.

Retrieve a Secret

Fetches the value of a secret from the specified Variable.

Batch Retrieval

Fetches multiple secret values in one invocation.

Policies

The following APIs help you to manage Conjur Policies.

API

Description

Replace a Policy

Loads or replaces a Conjur policy document.

Append to a Policy

Adds data to the existing Conjur policy.

Update a Policy

Modifies an existing Conjur policy.

Role-based control

The following APIs help you to manage Conjur role-based access controls.

API

Description

Show a Role

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

List a Role's Members

List members within a role.

List Resources

Lists resources within an organization account.

Show a Resource

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

Show Permitted Roles

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

Check Permission

Checks whether a role has a privilege on a resource.

Host Factory

The following APIs enable you to manage Host Factory features.

API

Description

Create Tokens

Creates one or more tokens which can be used to bootstrap applications.

Revoke Tokens

Revokes a token, immediately disabling it.

Create a Host

Creates an application (host) using the Host Factory and returns a JSON description of it.

Public keys

The following API lets you manage public key settings.

API

Description

Show Public Keys

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

Authenticators

Once an authenticator is configured and enabled, an authentication request can be sent to Conjur.

API

Description

OIDC Authenticator

Enables you to send an authentication request after the OIDC Authenticator is configured.

Azure Authenticator

When the Azure Authenticator is configured and enabled, an Azure instance can send an authentication request to Conjur.