consul/website/content/api-docs/acl/index.mdx

---
layout: api
page_title: ACLs - HTTP API
description: The /acl endpoints manage the Consul's ACL system.
---

# ACL HTTP API

-> **1.4.0+:** This API documentation is for Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api-docs/acl/legacy).

The `/acl` endpoints are used to manage ACL tokens and policies in Consul, [bootstrap the ACL system](#bootstrap-acls), [check ACL replication status](#check-acl-replication), and [translate rules](#translate-rules). There are additional pages for managing [tokens](/api-docs/acl/tokens) and [policies](/api-docs/acl/policies) with the `/acl` endpoints.

For more information on how to setup ACLs, please check
the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).

## Bootstrap ACLs

This endpoint does a special one-time bootstrap of the ACL system, making the first
management token if the [`acl.tokens.initial_management`](/docs/agent/config/config-files#acl_tokens_initial_management)
configuration entry is not specified in the Consul server configuration and if the
cluster has not been bootstrapped previously. This is available in Consul 0.9.1 and later,
and requires all Consul servers to be upgraded in order to operate.

This provides a mechanism to bootstrap ACLs without having any secrets present in Consul's
configuration files.

| Method | Path             | Produces           |
| ------ | ---------------- | ------------------ |
| `PUT`  | `/acl/bootstrap` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO`             | `none`            | `none`        | `none`       |

The corresponding CLI command is [`consul acl bootstrap`](/commands/acl/bootstrap).

### Sample Request

```shell-session
$ curl \
    --request PUT \
    http://127.0.0.1:8500/v1/acl/bootstrap
```

### Sample Response

-> **Deprecated** - The `ID` field in the response is for legacy compatibility and is a copy of the `SecretID` field. New
applications should ignore the `ID` field as it may be removed in a future major Consul version.

```json
{
  "ID": "527347d3-9653-07dc-adc0-598b8f2b0f4d",
  "AccessorID": "b5b1a918-50bc-fc46-dec2-d481359da4e3",
  "SecretID": "527347d3-9653-07dc-adc0-598b8f2b0f4d",
  "Description": "Bootstrap Token (Global Management)",
  "Policies": [
    {
      "ID": "00000000-0000-0000-0000-000000000001",
      "Name": "global-management"
    }
  ],
  "Local": false,
  "CreateTime": "2018-10-24T10:34:20.843397-04:00",
  "Hash": "oyrov6+GFLjo/KZAfqgxF/X4J/3LX0435DOBy9V22I0=",
  "CreateIndex": 12,
  "ModifyIndex": 12
}
```

You can detect if something has interfered with the ACL bootstrapping process by
checking the response code. A 200 response means that the bootstrap was a success, and
a 403 means that the cluster has already been bootstrapped, at which point you should
consider the cluster in a potentially compromised state.

The returned token will have unrestricted privileges to manage all details of the system.
It can then be used to further configure the ACL system. Please check the
[ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) for more details.

## Check ACL Replication

This endpoint returns the status of the ACL replication processes in the
datacenter. This is intended to be used by operators or by automation checking
to discover the health of ACL replication.

Please check the [ACL Replication tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-replication-multiple-datacenters)
for more details.

| Method | Path               | Produces           |
| ------ | ------------------ | ------------------ |
| `GET`  | `/acl/replication` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO`             | `consistent`      | `none`        | `none`       |

### Query Parameters

- `dc` `(string: "")` - Specifies the datacenter to query. This will default to
  the datacenter of the agent being queried.

### Sample Request

```shell-session
$ curl \
    --request GET \
    http://127.0.0.1:8500/v1/acl/replication
```

### Sample Response

```json
{
  "Enabled": true,
  "Running": true,
  "SourceDatacenter": "dc1",
  "ReplicationType": "tokens",
  "ReplicatedIndex": 1976,
  "ReplicatedTokenIndex": 2018,
  "LastSuccess": "2018-11-03T06:28:58Z",
  "LastError": "2016-11-03T06:28:28Z",
  "LastErrorMessage": "failed to retrieve ACL policy updates: RPC rate limit exceeded"
}
```

- `Enabled` - Reports whether ACL replication is enabled for the datacenter.

- `Running` - Reports whether the ACL replication process is running. The process
  may take approximately 60 seconds to begin running after a leader election
  occurs.

- `SourceDatacenter` - The authoritative ACL datacenter that ACLs are being
  replicated from and will match the
  [`primary_datacenter`](/docs/agent/config/config-files#primary_datacenter) configuration.

- `ReplicationType` - The type of replication that is currently in use.

  - `legacy` - (removed in Consul 1.11.0) ACL replication is in legacy mode and is replicating legacy ACL tokens.

  - `policies` - ACL replication is only replicating policies as token replication
    is disabled.

  - `tokens` - ACL replication is replicating both policies and tokens.

- `ReplicatedIndex` - The last index that was successfully replicated. Which data
  the replicated index refers to depends on the replication type. For `legacy`
  replication this can be compared with the value of the `X-Consul-Index` header
  returned by the [`/v1/acl/list`](/api-docs/acl/legacy#list-acls) endpoint to
  determine if the replication process has gotten all available ACLs. When in either
  `tokens` or `policies` mode, this index can be compared with the value of the
  `X-Consul-Index` header returned by the [`/v1/acl/policies`](/api-docs/acl/policies#list-policies)
  endpoint to determine if the policy replication process has gotten all available
  ACL policies. Note that ACL replication is rate limited so the indexes may lag behind
  the primary datacenter.

- `ReplicatedTokenIndex` - The last token index that was successfully replicated.
  This index can be compared with the value of the `X-Consul-Index` header returned
  by the [`/v1/acl/tokens`](/api-docs/acl/tokens#list-tokens) endpoint to determine
  if the replication process has gotten all available ACL tokens. Note that ACL
  replication is rate limited so the indexes may lag behind the primary
  datacenter.

- `LastSuccess` - The UTC time of the last successful sync operation. Since ACL
  replication is done with a blocking query, this may not update for up to 5
  minutes if there have been no ACL changes to replicate. A zero value of
  "0001-01-01T00:00:00Z" will be present if no sync has been successful.

- `LastError` - The UTC time of the last error encountered during a sync
  operation. If this time is later than `LastSuccess`, you can assume the
  replication process is not in a good state. A zero value of
  "0001-01-01T00:00:00Z" will be present if no sync has resulted in an error.

- `LastErrorMessage` - The last error message produced at the time of `LastError`.
  An empty string indicates that no sync has resulted in an error.

## Translate Rules

-> **Deprecated** - This endpoint was removed in Consul 1.11.0.
This endpoint was introduced in Consul 1.4.0 for migration from the previous ACL system.

This endpoint translates the legacy rule syntax into the latest syntax. It is intended
to be used by operators managing Consul's ACLs and performing legacy token to new policy
migrations.

| Method | Path                   | Produces     |
| ------ | ---------------------- | ------------ |
| `POST` | `/acl/rules/translate` | `text/plain` |

The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO`             | `none`            | `none`        | `acl:read`   |

The corresponding CLI command is [`consul acl translate-rules`](/commands/acl/translate-rules).

### Sample Payload

```hcl
agent "" {
   policy = "read"
}
```

### Sample Request

```shell-session
$ curl --request POST --data @rules.hcl http://127.0.0.1:8500/v1/acl/rules/translate
```

### Sample Response

```hcl
agent_prefix "" {
   policy = "read"
}
```

## Translate a Legacy Token's Rules

-> **Deprecated** - This endpoint was removed in Consul 1.11.0.
This endpoint was introduced in Consul 1.4.0 for migration from the previous ACL system.

This endpoint translates the legacy rules embedded within a legacy ACL into the latest
syntax. It is intended to be used by operators managing Consul's ACLs and performing
legacy token to new policy migrations. Note that this API requires the auto-generated
Accessor ID of the legacy token. This ID can be retrieved using the
[`/v1/acl/token/self`](/api-docs/acl/tokens#read-self-token) endpoint.

| Method | Path                                | Produces     |
| ------ | ----------------------------------- | ------------ |
| `GET`  | `/acl/rules/translate/:accessor_id` | `text/plain` |

The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO`             | `none`            | `none`        | `acl:read`   |

The corresponding CLI command is [`consul acl translate-rules`](/commands/acl/translate-rules).

### Sample Request

```shell-session
$ curl --request GET http://127.0.0.1:8500/v1/acl/rules/translate/4f48f7e6-9359-4890-8e67-6144a962b0a5
```

### Sample Response

```hcl
agent_prefix "" {
   policy = "read"
}
```

## Login to Auth Method

This endpoint was added in Consul 1.5.0 and is used to exchange an [auth
method](/docs/security/acl/auth-methods) bearer token for a newly-created
Consul ACL token.

| Method | Path         | Produces           |
| ------ | ------------ | ------------------ |
| `POST` | `/acl/login` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO`             | `none`            | `none`        | `none`       |

-> **Note** - To use the login process to create tokens in any connected
secondary datacenter, [ACL
replication](/docs/agent/config/config-files#acl_enable_token_replication) must be
enabled. Login requires the ability to create local tokens which is restricted
to the primary datacenter and any secondary datacenters with ACL token
replication enabled.

The corresponding CLI command is [`consul login`](/commands/login).

### Query Parameters

- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you use to login.
  You can also [specify the namespace through other methods](#methods-to-specify-namespace).

### JSON Request Body Schema

- `AuthMethod` `(string: <required>)` - The name of the auth method to use for login.

- `BearerToken` `(string: <required>)` - The bearer token to present to the
  auth method during login for authentication purposes. For the Kubernetes auth
  method this is a [Service Account Token
  (JWT)](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#service-account-tokens).

- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata
  linked to the token. Can be useful to track origins.

- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you use to login.
  This field takes precedence over the `ns` query parameter,
  one of several [other methods to specify the namespace](#methods-to-specify-namespace).

### Sample Payload

```json
{
  "AuthMethod": "minikube",
  "BearerToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
}
```

### Sample Request

```shell-session
$ curl \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8500/v1/acl/login
```

### Sample Response

```json
{
  "AccessorID": "926e2bd2-b344-d91b-0c83-ae89f372cd9b",
  "SecretID": "b78d37c7-0ca7-5f4d-99ee-6d9975ce4586",
  "Description": "token created via login",
  "Roles": [
    {
      "ID": "3356c67c-5535-403a-ad79-c1d5f9df8fc7",
      "Name": "demo"
    }
  ],
  "ServiceIdentities": [
    {
      "ServiceName": "example"
    }
  ],
  "Local": true,
  "AuthMethod": "minikube",
  "CreateTime": "2019-04-29T10:08:08.404370762-05:00",
  "Hash": "nLimyD+7l6miiHEBmN/tvCelAmE/SbIXxcnTzG3pbGY=",
  "CreateIndex": 36,
  "ModifyIndex": 36
}
```

## Logout from Auth Method

This endpoint was added in Consul 1.5.0 and is used to destroy a token created
via the [login endpoint](#login-to-auth-method). The token deleted is specified
with the `X-Consul-Token` header or the `token` query parameter.

| Method | Path          | Produces           |
| ------ | ------------- | ------------------ |
| `POST` | `/acl/logout` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO`             | `none`            | `none`        | `none`       |

-> **Note** - This endpoint requires no specific privileges as it is just
deleting a token for which you already must possess its secret.

The corresponding CLI command is [`consul logout`](/commands/logout).

### Sample Request

```shell-session
$ curl \
    --header "X-Consul-Token: b78d37c7-0ca7-5f4d-99ee-6d9975ce4586" \
    --request POST \
    http://127.0.0.1:8500/v1/acl/logout
```

## OIDC Authorization URL Request

<EnterpriseAlert>
  {' '}
  This is an enterprise only endpoint.
</EnterpriseAlert>

This endpoint was added in Consul 1.8.0 and is used to obtain an authorization
URL from Consul to start an [OIDC login flow](/docs/security/acl/auth-methods/oidc).

| Method | Path                 | Produces           |
| ------ | -------------------- | ------------------ |
| `POST` | `/acl/oidc/auth-url` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO`             | `none`            | `none`        | `none`       |

-> **Note** - To use the login process to create tokens in any connected
secondary datacenter, [ACL
replication](/docs/agent/config/config-files#acl_enable_token_replication) must be
enabled. Login requires the ability to create local tokens which is restricted
to the primary datacenter and any secondary datacenters with ACL token
replication enabled.

### Query Parameters

- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you use to login.
  You can also [specify the namespace through other methods](#methods-to-specify-namespace).

### JSON Request Body Schema

- `AuthMethod` `(string: <required>)` - The name of the auth method to use for
  login. This must be of type [`oidc`](/docs/security/acl/auth-methods/oidc).

- `RedirectURI` `(string: <required>)` - See [Redirect
  URIs](/docs/security/acl/auth-methods/oidc#redirect-uris) for more information.

- `ClientNonce` `(string: "")` - Optional client-provided nonce that must match
  during callback, if present.

- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata
  linked to the token. Can be useful to track origins.

- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you use to login.
  This field takes precedence over the `ns` query parameter,
  one of several [other methods to specify the namespace](#methods-to-specify-namespace).

  This must match the namespace provided on the [OIDC Callback](#oidc-callback).

### Sample Payload

```json
{
  "AuthMethod": "auth0",
  "RedirectURI": "http://localhost:8550/oidc/callback"
}
```

### Sample Request

```shell-session
$ curl \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8500/v1/acl/oidc/auth-url
```

### Sample Response

```json
{
  "AuthURL": "https://myprovider.com/authorize?client_id=..."
}
```

## OIDC Callback

<EnterpriseAlert>
  {' '}
  This is an enterprise only endpoint.
</EnterpriseAlert>

This endpoint was added in Consul 1.8.0 and is used to exchange an OIDC
authorization code for an OIDC ID Token. The ID token will in turn be exchanged
for a newly-created Consul ACL token.

| Method | Path                 | Produces           |
| ------ | -------------------- | ------------------ |
| `POST` | `/acl/oidc/callback` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------ |
| `NO`             | `none`            | `none`        | `none`       |

-> **Note** - To use the login process to create tokens in any connected
secondary datacenter, [ACL
replication](/docs/agent/config/config-files#acl_enable_token_replication) must be
enabled. Login requires the ability to create local tokens which is restricted
to the primary datacenter and any secondary datacenters with ACL token
replication enabled.

### Query Parameters

- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you use to login.
  You can also [specify the namespace through other methods](#methods-to-specify-namespace).

### JSON Request Body Schema

- `AuthMethod` `(string: <required>)` - The name of the auth method to use for
  login. This must be of type [`oidc`](/docs/security/acl/auth-methods/oidc).

- `State` `(string: <required>)` - Opaque state ID that is part of the
  Authorization URL and will be included in the the redirect following
  successful authentication on the provider.

- `Code` `(string: <required>)` - Provider-generated authorization code that
  Consul will exchange for an ID token.

- `ClientNonce` `(string: "")` - Optional client-provided nonce that must match
  the one provided in the auth url request, if present.

- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata
  linked to the token. Can be useful to track origins.

- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the auth method you use to login.
  This field takes precedence over the `ns` query parameter,
  one of several [other methods to specify the namespace](#methods-to-specify-namespace).

### Sample Payload

```json
{
  "AuthMethod": "auth0",
  "State": "aa3f1903c2f5eac666e6f92e804cf7fc0ff1d15b",
  "Code": "dn0u9oM9WegYBEnp"
}
```

### Sample Request

```shell-session
$ curl \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8500/v1/acl/oidc/callback
```

### Sample Response

```json
{
  "AccessorID": "926e2bd2-b344-d91b-0c83-ae89f372cd9b",
  "SecretID": "b78d37c7-0ca7-5f4d-99ee-6d9975ce4586",
  "Description": "token created via OIDC login",
  "Roles": [
    {
      "ID": "3356c67c-5535-403a-ad79-c1d5f9df8fc7",
      "Name": "demo"
    }
  ],
  "ServiceIdentities": [
    {
      "ServiceName": "example"
    }
  ],
  "Local": true,
  "AuthMethod": "auth0",
  "CreateTime": "2019-04-29T10:08:08.404370762-05:00",
  "Hash": "nLimyD+7l6miiHEBmN/tvCelAmE/SbIXxcnTzG3pbGY=",
  "CreateIndex": 36,
  "ModifyIndex": 36
}
```

## Methods to Specify Namespace <EnterpriseAlert inline />

Some ACL endpoints support several methods for specifying the namespace of the resource
with the following order of precedence:
1. Namespace` field of the JSON request body -
  only applies to endpoints that accept an JSON request body
1. ns` query parameter
1. X-Consul-Namespace` request header
1. Namespace is inherited from the namespace of the request's ACL token (if any)
1. The `default` namespace