ACL Role HTTP API

1.5.0+: The role APIs are available in Consul versions 1.5.0 and newer.

The /acl/role endpoints create, read, update, list and delete ACL roles in Consul.

For more information on how to setup ACLs, refer to the following resources:

Create a Role

This endpoint creates a new ACL role.

Method	Path	Produces
`PUT`	`/acl/role`	`application/json`

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`NO`	`none`	`none`	`acl:write`

The corresponding CLI command is consul acl role create.

Query Parameters

ns (string: "") Enterprise - Specifies the namespace of the role you create. You can also specify the namespace through other methods.

JSON Request Body Schema

Name (string: <required>) - Specifies a name for the ACL role. The name can contain alphanumeric characters, dashes -, and underscores _. This name must be unique.
Description (string: "") - Free form human readable description of the role.
Policies (array<PolicyLink>) - The list of policies that should be applied to the role. A PolicyLink is an object with an "ID" and/or "Name" field to specify a policy. With the PolicyLink, roles can be linked to policies either by the policy name or by the policy ID. When policies are linked by name they will be internally resolved to the policy ID. With linking roles internally by IDs, Consul enables policy renaming without breaking tokens.
TemplatedPolicies (list of maps) - The list of templated policies that should be applied to the role.
- TemplateName (string: <required>) - The templated policy name.
- TemplateVariables (map of strings|maps: <optional>) - The templated policy variables. Not all templated policies require variables.
ServiceIdentities (array<ServiceIdentity>) - The list of service identities that should be applied to the role.
- ServiceName (string: <required>) - The name of the service. The name must be no longer than 256 characters, must start and end with a lowercase alphanumeric character, and can only contain lowercase alphanumeric characters as well as - and _.
- Datacenters (array<string>) - Specifies the datacenters the effective policy is valid within. When no datacenters are provided the effective policy is valid in all datacenters including those which do not yet exist but may in the future.
NodeIdentities (array<NodeIdentity>) - The list of node identities that should be applied to the role.
- NodeName (string: <required>) - The name of the node. The name must be no longer than 256 characters, must start and end with a lowercase alphanumeric character, and can only contain lowercase alphanumeric characters as well as - and _.
- Datacenter (string: <required>) - Specifies the nodes datacenter. This will result in effective policy only being valid in that datacenter.
Namespace (string: "") Enterprise - Specifies the namespace of the role you create. This field takes precedence over the ns query parameter, one of several other methods to specify the namespace.

Partition (string: "") - Enterprise The partition to use. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

Sample Payload

{
  "Name": "example-role",
  "Description": "Showcases all input parameters",
  "Policies": [
    {
      "ID": "783beef3-783f-f41f-7422-7087dc272765"
    },
    {
      "Name": "node-read"
    }
  ],
  "TemplatedPolicies": [
     {
      "TemplateName": "builtin/service",
      "TemplateVariables": {
        "Name": "api"
      }
    },
    {
      "TemplateName": "builtin/dns"
    }
  ],
  "ServiceIdentities": [
    {
      "ServiceName": "web"
    },
    {
      "ServiceName": "db",
      "Datacenters": ["dc1"]
    }
  ],
  "NodeIdentities": [
    {
      "NodeName": "node-1",
      "Datacenter": "dc2"
    }
  ]
}

Sample Request

$ curl --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/acl/role

Sample Response

{
  "ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
  "Name": "example-role",
  "Description": "Showcases all input parameters",
  "Policies": [
    {
      "ID": "783beef3-783f-f41f-7422-7087dc272765",
      "Name": "node-read"
    }
  ],
  "ServiceIdentities": [
    {
      "ServiceName": "web"
    },
    {
      "ServiceName": "db",
      "Datacenters": ["dc1"]
    }
  ],
  "NodeIdentities": [
    {
      "NodeName": "node-1",
      "Datacenter": "dc2"
    }
  ],
  "TemplatedPolicies": [
    {
      "TemplateID": "00000000-0000-0000-0000-000000000003",
      "TemplateName": "builtin/service",
      "TemplateVariables": {
        "Name": "api"
      }
    },
    {
      "TemplateID": "00000000-0000-0000-0000-000000000005",
      "TemplateName": "builtin/dns"
    }
  ],
  "Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
  "CreateIndex": 57,
  "ModifyIndex": 57
}

Read a Role

This endpoint reads an ACL role with the given ID. If no role exists with the given ID, a 404 is returned instead of a 200 response.

Method	Path	Produces
`GET`	`/acl/role/:id`	`application/json`

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`YES`	`all`	`none`	`acl:read`

The corresponding CLI command is consul acl role read.

Path Parameters

id (string: <required>) - Specifies the UUID of the role you lookup.

Query Parameters

ns (string: "") Enterprise - Specifies the namespace of the role you lookup. You can also specify the namespace through other methods.

partition (string: "") Enterprise - The partition to use. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

Sample Request

$ curl --request GET http://127.0.0.1:8500/v1/acl/role/aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4

Sample Response

{
  "ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
  "Name": "example-role",
  "Description": "Showcases all input parameters",
  "Policies": [
    {
      "ID": "783beef3-783f-f41f-7422-7087dc272765",
      "Name": "node-read"
    }
  ],
  "ServiceIdentities": [
    {
      "ServiceName": "web"
    },
    {
      "ServiceName": "db",
      "Datacenters": ["dc1"]
    }
  ],
  "NodeIdentities": [
    {
      "NodeName": "node-1",
      "Datacenter": "dc2"
    }
  ],
  "TemplatedPolicies": [
    {
      "TemplateID": "00000000-0000-0000-0000-000000000003",
      "TemplateName": "builtin/service",
      "TemplateVariables": {
        "Name": "api"
      }
    },
    {
      "TemplateID": "00000000-0000-0000-0000-000000000005",
      "TemplateName": "builtin/dns"
    }
  ],
  "Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
  "CreateIndex": 57,
  "ModifyIndex": 57
}

Read a Role by Name

This endpoint reads an ACL role with the given name. If no role exists with the given name, a 404 is returned instead of a 200 response.

Method	Path	Produces
`GET`	`/acl/role/name/:name`	`application/json`

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`YES`	`all`	`none`	`acl:read`

The corresponding CLI command is consul acl role read -name=<string>.

Path Parameters

name (string: <required>) - Specifies the name of the ACL role to read.

Query Parameters

ns (string: "") Enterprise - Specifies the namespace of the role you lookup. You can also specify the namespace through other methods.

partition (string: "") Enterprise - The partition to use. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

Sample Request

$ curl --request GET http://127.0.0.1:8500/v1/acl/role/name/example-role

Sample Response

{
  "ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
  "Name": "example-role",
  "Description": "Showcases all input parameters",
  "Policies": [
    {
      "ID": "783beef3-783f-f41f-7422-7087dc272765",
      "Name": "node-read"
    }
  ],
  "ServiceIdentities": [
    {
      "ServiceName": "web"
    },
    {
      "ServiceName": "db",
      "Datacenters": ["dc1"]
    }
  ],
  "NodeIdentities": [
    {
      "NodeName": "node-1",
      "Datacenter": "dc2"
    }
  ],
  "TemplatedPolicies": [
    {
      "TemplateID": "00000000-0000-0000-0000-000000000003",
      "TemplateName": "builtin/service",
      "TemplateVariables": {
        "Name": "api"
      }
    },
    {
      "TemplateID": "00000000-0000-0000-0000-000000000005",
      "TemplateName": "builtin/dns"
    }
  ],
  "Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
  "CreateIndex": 57,
  "ModifyIndex": 57
}

Update a Role

This endpoint updates an existing ACL role.

Method	Path	Produces
`PUT`	`/acl/role/:id`	`application/json`

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`NO`	`none`	`none`	`acl:write`

The corresponding CLI command is consul acl role update.

Path Parameters

id (string: <required>) - Specifies the UUID of the role you update.

Query Parameters

ns (string: "") Enterprise - Specifies the namespace of the role you update. You can also specify the namespace through other methods.

JSON Request Body Schema

ID (string: <optional>) - If specified, this field must be an exact match with the id path parameter.
Name (string: <required>) - Specifies a name for the ACL role. The name can only contain alphanumeric characters as well as - and _ and must be unique.
Description (string: "") - Free form human readable description of the role.
Policies (array<PolicyLink>) - The list of policies that should be applied to the role. A PolicyLink is an object with an "ID" and/or "Name" field to specify a policy. With the PolicyLink, roles can be linked to policies either by the policy name or by the policy ID. When policies are linked by name they will be internally resolved to the policy ID. With linking roles internally by IDs, Consul enables policy renaming without breaking tokens.
ServiceIdentities (array<ServiceIdentity>) - The list of service identities that should be applied to the role. Added in Consul 1.5.0.
NodeIdentities (array<NodeIdentity>) - The list of node identities that should be applied to the role. Added in Consul 1.8.1.
Namespace (string: "") Enterprise - Specifies the namespace of the role you update. This field takes precedence over the ns query parameter, one of several other methods to specify the namespace.

Partition (string: "") - Enterprise The partition to use. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

Sample Payload

{
  "ID": "8bec74a4-5ced-45ed-9c9d-bca6153490bb",
  "Name": "example-two",
  "Policies": [
    {
      "Name": "node-read"
    }
  ],
  "ServiceIdentities": [
    {
      "ServiceName": "db"
    }
  ],
  "NodeIdentities": [
    {
      "NodeName": "node-1",
      "Datacenter": "dc2"
    }
  ],
  "TemplatedPolicies": [
    {
      "TemplateName": "builtin/dns"
    }
  ]
}

Sample Request

$ curl --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/acl/role/8bec74a4-5ced-45ed-9c9d-bca6153490bb

Sample Response

{
  "ID": "8bec74a4-5ced-45ed-9c9d-bca6153490bb",
  "Name": "example-two",
  "Policies": [
    {
      "ID": "783beef3-783f-f41f-7422-7087dc272765",
      "Name": "node-read"
    }
  ],
  "ServiceIdentities": [
    {
      "ServiceName": "db"
    }
  ],
  "NodeIdentities": [
    {
      "NodeName": "node-1",
      "Datacenter": "dc2"
    }
  ],
  "TemplatedPolicies": [
    {
      "TemplateID": "00000000-0000-0000-0000-000000000005",
      "TemplateName": "builtin/dns"
    }
  ],
  "Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
  "CreateIndex": 14,
  "ModifyIndex": 28
}

Delete a Role

This endpoint deletes an ACL role.

Method	Path	Produces
`DELETE`	`/acl/role/:id`	`application/json`

Even though the return type is application/json, the value is either true or false indicating whether the delete succeeded.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`NO`	`none`	`none`	`acl:write`

The corresponding CLI command is consul acl role delete.

Path Parameters

id (string: <required>) - Specifies the UUID of the role you delete.

Query Parameters

ns (string: "") Enterprise - Specifies the namespace of the role you delete. You can also specify the namespace through other methods.

partition (string: "") Enterprise - The partition to use. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

Sample Request

$ curl --request DELETE \
    http://127.0.0.1:8500/v1/acl/role/8f246b77-f3e1-ff88-5b48-8ec93abf3e05

Sample Response

true

List Roles

This endpoint lists all the ACL roles.

Method	Path	Produces
`GET`	`/acl/roles`	`application/json`

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`YES`	`all`	`none`	`acl:read`

The corresponding CLI command is consul acl role list.

Query Parameters

policy (string: "") - Filters the role list to those roles that are linked with this specific policy ID.
ns (string: "") Enterprise - Return only the roles in the specified namespace. The namespace may be specified as '*' to return results for all namespaces. You can also specify the namespace through other methods.

partition (string: "") Enterprise - The partition to use. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

Sample Request

$ curl --request GET http://127.0.0.1:8500/v1/acl/roles

Sample Response

[
  {
    "ID": "5e52a099-4c90-c067-5478-980f06be9af5",
    "Name": "node-read",
    "Description": "",
    "Policies": [
      {
        "ID": "783beef3-783f-f41f-7422-7087dc272765",
        "Name": "node-read"
      }
    ],
    "Hash": "K6AbfofgiZ1BEaKORBloZf7WPdg45J/PipHxQiBlK1U=",
    "CreateIndex": 50,
    "ModifyIndex": 50
  },
  {
    "ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
    "Name": "example-role",
    "Description": "Showcases all input parameters",
    "Policies": [
      {
        "ID": "783beef3-783f-f41f-7422-7087dc272765",
        "Name": "node-read"
      }
    ],
    "ServiceIdentities": [
      {
        "ServiceName": "web"
      },
      {
        "ServiceName": "db",
        "Datacenters": ["dc1"]
      }
    ],
    "NodeIdentities": [
      {
        "NodeName": "node-1",
        "Datacenter": "dc2"
      }
    ],
    "Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
    "CreateIndex": 57,
    "ModifyIndex": 57
  }
]

Methods to specify namespace Enterprise

ACL role endpoints support several methods for specifying the namespace of the ACL role resources with the following order of precedence:

Namespace field of the JSON request body - only applies to create and update endpoints
ns query parameter
X-Consul-Namespace request header
Namespace is inherited from the namespace of the request's ACL token (if any)
The default namespace

ACL Role HTTP API

Create a Role

Query Parameters

JSON Request Body Schema

Sample Payload

Sample Request

Sample Response

Read a Role

Path Parameters

Query Parameters

Sample Request

Sample Response

Read a Role by Name

Path Parameters

Query Parameters

Sample Request

Sample Response

Update a Role

Path Parameters

Query Parameters

JSON Request Body Schema

Sample Payload

Sample Request

Sample Response

Delete a Role

Path Parameters

Query Parameters

Sample Request

Sample Response

List Roles

Query Parameters

Sample Request

Sample Response

Methods to specify namespace EnterpriseEnterprise

Methods to specify namespace Enterprise