The !host statement creates a host role and a host resource. A host represents an application. Conjur allows an application to authenticate to Conjur and access secrets that it has permission to access.


- !host
  id: <name>
  owner: !<kind-of-role> <role-name>
    <key>: <value>
  restricted_to: <network range>


Attributes Description


Required. Identifies the host resource name and the role name.

This id becomes the last component in the host login name.


Optional. If owner is not provided, a resource inherits its owner from its policy.

If owner is provided, the role that is named as owner must already exist. You can declare the owner in the current policy if the declaration appears before any statement that references it.


Custom annotations are supported.

authn/api-key: true

Custom annotations provide a way to store meta data about a resource. Annotations are useful for human users and automated processing. Conjur API calls can retrieve annotation values from the Conjur database.


Restricts authentication from the specified network range. This can include:

  • one or more IP addresses

  • one or more CIDR ranges


Trusted proxies must be configured before you can use this feature. For more information, see Client IP Address Sourcing.


A host represents a workload: a server, VM, job, container, application, or any other type of coded or automated actor. Each workload has an identity (host id). Using that identity, a workload can authenticate to Conjur.

While a host can represent a script, application, or microservice, we recommend using the host resource to represent the running environment for those entities, and using a layer to represent the executing entity. See Layer for an example.

After declaring a host, you can assign permissions to that host role using the !permit statement. For example, you can give a host permission to fetch a username and password to log into an infrastructure database.

More likely, you would first use the !grant statement to add the host to a layer, and manage permissions on the layer. By using layers, you can manage multiple hosts as a set, in the same way that you manage a set of users by placing them in a group.

When you load a policy that declares a host, Conjur creates credentials specific to that host. A host uses its credentials to authenticate to Conjur. See the API documentation for a description of the two-step process required for a host to authenticate to Conjur.

Additional ways to create hosts

There are other ways that hosts are created in addition to explicitly declaring them in policy. When these other methods are used, you can get the host ids and an API key from the tooling that created the hosts.

  • A Host Factory creates multiple hosts without having to declare each one individually.

  • The Conjur integrations, such as Ansible, VMware Tanzu, Puppet, and Kubernetes, each include tooling to automatically create hosts relevant to the integration.

Host credentials

A host's credentials are its login name and an API key/provider authentication token.

A host needs access to its credentials to authenticate to Conjur and get access to secrets.

You must ensure that the credentials are available to the host for later use. After you load the policy, you need to save the credentials manually and make sure that the host has access to these credentials.

  • For a host that is long-running, such as servers and VMs, the typical way to store the credentials is in a file accessible to the host. For example: /etc/conjur.identity.

  • For a host that can accept configuration through the environment, such as Docker containers, CI jobs, Heroku applications, use environment variables CONJUR_AUTHN_LOGIN and CONJUR_AUTHN_API_KEY.

For short-lived hosts, such as some containers, Kubernetes Pods, or temporary VMs, the Conjur Host-Factory tooling manages identity.

Host login name

A host's login name for authenticating to Conjur is a string consisting of the constant host/ followed by the host's fully qualified id.


A fully qualified ID is the entire policy namespace that describes where the host is declared in the hierarchy of policy branches, omitting root. The last component is the host id attribute in the !host statement. If a host is created by a Host Factory or a Conjur integration, you must obtain the id value from those sources.


When the string is used in an HTTP request with the API, the entire string must be URL-encoded.

The following table shows examples for host login name in plaintext and URL-encoded.

Policy where host is declared Plaintext login name

URL-encoded login name










API key or Provider authentication token

API key vs Authentication token

Authentication mode


API key

An API key is a randomly generated secret assigned by Conjur when the host is created, if so defined in the host policy. When you load policy that creates a host, the output from the load command or API request includes the API key for each host that was created.

The following sample output shows the API keys that were generated after loading a host policy that declared two hosts:

"dev:host:frontend/frontend-01": "33f0ppq25sy3kx1qx630b2mvth2126nscms28bk7qy3hrwdmna86fh", 
"dev:host:frontend/frontend-02": "2w7dkpv2eszx6nvgvgvy2q2z5seq6n3gk33z1fem3z7f6493dqtwhm" 

A user who has the appropriate permissions on a workload (host resource) can reset (rotate) the API key if it is lost or compromised. Authenticated users with appropriate permission can get the current API key value for a host using the API or Conjur CLI.

Provider authentication token

If you want your workload to authenticate to Conjur using a provider authentication token, the host policy must include relevant provider authentication details. When the workload tries to authenticate to Conjur, the workload first uses these authentication details to get an authentication token from the relevant provider. This provider authentication token is then used to authenticate the workload to Conjur.



A role needs the following privileges to perform actions on a host resource:

Privileges required to perform actions on hosts
Action Required privileges

Declare a new host

create privilege on the policy in which the host is declared

Update host information

update privilege on the host

Rotate a host's API key

update privilege on the host

Delete a host

update privilege on the host

Add a host to a layer

update privilege on the layer

Get host information

execute permission on the host

Verify if a host id is defined

read permission on the host

Best practices

  1. hosts defined in a policy are generally long-lasting (static) hosts. They should be assigned to a layer using a !grant statement and managed as part of a layer.

  2. For short-lived hosts, use a Host Factory or one of the Conjur integrations.

  3. Assignment to layers should be the primary way for hosts to get privileges. For example, add a host to a layer, and permit the layer to access a set of variables.

  4. For applications, microservices, and other executables, define the underlying running environment as the host, and use a layer to represent the workload and manage secrets access. For an example, see Layer.