ACL Policies HTTP API

The /acl/policies and /acl/policy/ endpoints are used to manage ACL policies. For more details about ACLs, please see the ACL Guide.

List Policies

This endpoint lists all ACL policies. This lists the policies that have been replicated to the region, and may lag behind the authoritative region.

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

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

Blocking Queries	Consistency Modes	ACL Required
`YES`	`all`	`management` for all policies. Output when given a non-management token will be limited to the policies on the token itself

Parameters

prefix (string: "") - Specifies a string to filter ACL policies based on a name prefix. This is specified as a query string parameter.

Sample Request

$ curl \
    https://localhost:4646/v1/acl/policies

$ curl \
    https://localhost:4646/v1/acl/policies?prefix=prod

Sample Response

[
  {
    "Name": "foo",
    "Description": "",
    "CreateIndex": 12,
    "ModifyIndex": 13
  }
]

Create or Update Policy

This endpoint creates or updates an ACL Policy. This request is always forwarded to the authoritative region.

Method	Path	Produces
`POST`	`/acl/policy/:policy_name`	`(empty body)`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`management`

Parameters

Name (string: <required>) - Specifies the name of the policy. Creates the policy if the name does not exist, otherwise updates the existing policy.
Description (string: <optional>) - Specifies a human readable description.
Rules (string: <required>) - Specifies the Policy rules in HCL or JSON format.
JobACL (JobACL: <optional>) - Associates the policy with a given namespace, job, group, or task. Refer to Workload Associated ACL Policies for more information.
- Namespace (string: <optional>) - The namespace to attach the policy. Required if JobID is set.
- JobID (string: <optional>) - The job to attach to the policy. Required if Group is set.
- Group (string: <optional>) - The group to attach to the policy. Required if Task is set.
- Task (string: <optional>) - The task to attach to the policy.

Sample Payload

{
  "Name": "my-policy",
  "Description": "This is a great policy",
  "Rules": "",
  "JobACL": {
    "Namespace": "default",
    "JobID": "example"
  }
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/acl/policy/my-policy

Read Policy

This endpoint reads an ACL policy with the given name. This queries the policy that have been replicated to the region, and may lag behind the authoritative region.

Method	Path	Produces
`GET`	`/acl/policy/:policy_name`	`application/json`

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

Blocking Queries	Consistency Modes	ACL Required
`YES`	`all`	`management` or token with access to policy

Sample Request

$ curl \
    https://localhost:4646/v1/acl/policy/foo

Sample Response

{
  "Name": "foo",
  "Rules": "",
  "Description": "",
  "CreateIndex": 12,
  "ModifyIndex": 13
}

Delete Policy

This endpoint deletes the named ACL policy. This request is always forwarded to the authoritative region.

Method	Path	Produces
`DELETE`	`/acl/policy/:policy_name`	`(empty body)`

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking Queries	ACL Required
`NO`	`management`

Parameters

policy_name (string: <required>) - Specifies the policy name to delete.

Sample Request

$ curl \
    --request DELETE \
    https://localhost:4646/v1/acl/policy/foo