Annotation reference

Annotations provide information about a Conjur resource.


Annotations offer a way to assign metadata and descriptive information to a Conjur resource. Any Conjur resource can have annotations associated with it in policy.

Annotations are a type of mapping node in policy. The required mapping node name is annotations, followed by a colon. This node name is followed by one or more key-value pairs on separate lines, indented under the annotations: node name. The indentation is required.

The format of the key-value pair is key: value, requiring the colon followed by a space.


After you change an annotation in a policy, you need to reload your adjusted policy file using the --replace (PUT) option for the changes to take effect. For more information about policy load modes, see Policy load modes.

Here is an example annotation on a host. The annotation key in this example is description. The value is the phrase that appears after the colon.

- !host
    description: Hypertext web server

Conjur supports the following types of annotations: 

Predefined annotations

Predefined annotations support Conjur features. For these annotations, the annotation key is predefined and the value may be predefined with expected values.

Custom annotations

Custom annotations are free-form, defined by you for your own use. For these, you define the key and the value.

Benefits of using annotations

Annotations provide the following benefits:

  • Annotations provide a way to add metadata and organization to your Conjur resources

  • Annotations can help to explain the purpose of each statement in the policy. Descriptive annotations can help users better understand the objects in the Conjur system

  • Annotations support following UI-specific features: Editable annotation on groups and layers and Host identifiers for integrations

  • Conjur uses annotations for some workflows , for example, variable rotation and expiration are based on annotations

  • Custom code and scripts can use annotation values to perform custom operations, such as scripted updates to a system

Permissions for annotations

The rights to create, modify, and read annotations are protected by RBAC.




Required to create and modify annotations


  • Required to view annotations
  • After an annotation is loaded into Conjur as part of a policy, it is available through the API and the UI, subject to a read permission check.