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.

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 hostrepresents an application: a server, VM, job, container, or any other type of coded or automated actor. Each application has an identity (host id). Using that identity, an application 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 Host 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 obtain the host ids and API keys 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.

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










Host API key

The API key is a randomly generated secret assigned by Conjur when the host is created. 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.

Here is example output from a policy load that declares two hosts:

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

A user who has the appropriate permissions on a 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 CLI.

A host needs access to its credentials to authenticate to Conjur and get access to secrets. You must ensure that the host credentials are available to the host for later use by saving the credentials on the host.

Saving the credentials is a manual process after loading the policy on the command line, or if using the API, another step in your application. Save identity in files or in environment variables.

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

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



Actions on a host resource require the following permissions.

To perform these actions... A role needs these 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 application and manage secrets access. See Host for an example.