1--- 2layout: api 3page_title: ACLs - HTTP API 4sidebar_current: api-acl 5description: |- 6 The /acl endpoints manage the Consul's ACL system. 7--- 8 9-> **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/acl/legacy.html) 10 11# ACL HTTP API 12 13The `/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/acl/tokens.html) and [policies](/api/acl/policies.html) with the `/acl` endpoints. 14 15For more information on how to setup ACLs, please see 16the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/production-acls). 17 18## Bootstrap ACLs 19 20This endpoint does a special one-time bootstrap of the ACL system, making the first 21management token if the [`acl.tokens.master`](/docs/agent/options.html#acl_tokens_master) 22configuration entry is not specified in the Consul server configuration and if the 23cluster has not been bootstrapped previously. This is available in Consul 0.9.1 and later, 24and requires all Consul servers to be upgraded in order to operate. 25 26This provides a mechanism to bootstrap ACLs without having any secrets present in Consul's 27configuration files. 28 29| Method | Path | Produces | 30| ------ | ---------------------------- | -------------------------- | 31| `PUT` | `/acl/bootstrap` | `application/json` | 32 33The table below shows this endpoint's support for 34[blocking queries](/api/features/blocking.html), 35[consistency modes](/api/features/consistency.html), 36[agent caching](/api/features/caching.html), and 37[required ACLs](/api/index.html#authentication). 38 39| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 40| ---------------- | ----------------- | ------------- | ------------ | 41| `NO` | `none` | `none` | `none` | 42 43### Sample Request 44 45```text 46$ curl \ 47 --request PUT \ 48 http://127.0.0.1:8500/v1/acl/bootstrap 49``` 50 51### Sample Response 52 53-> **Deprecated** - The `ID` field in the response is for legacy compatibility and is a copy of the `SecretID` field. New 54applications should ignore the `ID` field as it may be removed in a future major Consul version. 55 56```json 57{ 58 "ID": "527347d3-9653-07dc-adc0-598b8f2b0f4d", 59 "AccessorID": "b5b1a918-50bc-fc46-dec2-d481359da4e3", 60 "SecretID": "527347d3-9653-07dc-adc0-598b8f2b0f4d", 61 "Description": "Bootstrap Token (Global Management)", 62 "Policies": [ 63 { 64 "ID": "00000000-0000-0000-0000-000000000001", 65 "Name": "global-management" 66 } 67 ], 68 "Local": false, 69 "CreateTime": "2018-10-24T10:34:20.843397-04:00", 70 "Hash": "oyrov6+GFLjo/KZAfqgxF/X4J/3LX0435DOBy9V22I0=", 71 "CreateIndex": 12, 72 "ModifyIndex": 12 73} 74``` 75 76You can detect if something has interfered with the ACL bootstrapping process by 77checking the response code. A 200 response means that the bootstrap was a success, and 78a 403 means that the cluster has already been bootstrapped, at which point you should 79consider the cluster in a potentially compromised state. 80 81The returned token will have unrestricted privileges to manage all details of the system. 82It can then be used to further configure the ACL system. Please see the 83[ACL Guide](https://learn.hashicorp.com/consul/security-networking/production-acls) for more details. 84 85## Check ACL Replication 86 87This endpoint returns the status of the ACL replication processes in the 88datacenter. This is intended to be used by operators or by automation checking 89to discover the health of ACL replication. 90 91Please see the [ACL Replication Guide](https://learn.hashicorp.com/consul/day-2-operations/acl-replication) 92for more details. 93 94| Method | Path | Produces | 95| ------ | ---------------------------- | -------------------------- | 96| `GET` | `/acl/replication` | `application/json` | 97 98The table below shows this endpoint's support for 99[blocking queries](/api/features/blocking.html), 100[consistency modes](/api/features/consistency.html), 101[agent caching](/api/features/caching.html), and 102[required ACLs](/api/index.html#authentication). 103 104| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 105| ---------------- | ----------------- | ------------- | ------------ | 106| `NO` | `consistent` | `none` | `none` | 107 108### Parameters 109 110- `dc` `(string: "")` - Specifies the datacenter to query. This will default to 111 the datacenter of the agent being queried. This is specified as part of the 112 URL as a query parameter. 113 114### Sample Request 115 116```text 117$ curl \ 118 --request GET \ 119 http://127.0.0.1:8500/v1/acl/replication 120``` 121 122### Sample Response 123 124```json 125{ 126 "Enabled": true, 127 "Running": true, 128 "SourceDatacenter": "dc1", 129 "ReplicationType" : "tokens", 130 "ReplicatedIndex": 1976, 131 "ReplicatedTokenIndex": 2018, 132 "LastSuccess": "2018-11-03T06:28:58Z", 133 "LastError": "2016-11-03T06:28:28Z" 134} 135``` 136 137- `Enabled` - Reports whether ACL replication is enabled for the datacenter. 138 139- `Running` - Reports whether the ACL replication process is running. The process 140 may take approximately 60 seconds to begin running after a leader election 141 occurs. 142 143- `SourceDatacenter` - The authoritative ACL datacenter that ACLs are being 144 replicated from and will match the 145 [`primary_datacenter`](/docs/agent/options.html#primary_datacenter) configuration. 146 147- `ReplicationType` - The type of replication that is currently in use. 148 149 - `legacy` - ACL replication is in legacy mode and is replicating legacy ACL tokens. 150 151 - `policies` - ACL replication is only replicating policies as token replication 152 is disabled. 153 154 - `tokens` - ACL replication is replicating both policies and tokens. 155 156- `ReplicatedIndex` - The last index that was successfully replicated. Which data 157 the replicated index refers to depends on the replication type. For `legacy` 158 replication this can be compared with the value of the `X-Consul-Index` header 159 returned by the [`/v1/acl/list`](/api/acl/legacy.html#acl_list) endpoint to 160 determine if the replication process has gotten all available ACLs. When in either 161 `tokens` or `policies` mode, this index can be compared with the value of the 162 `X-Consul-Index` header returned by the [`/v1/acl/policies`](/api/acl/policies.html#list-policies) 163 endpoint to determine if the policy replication process has gotten all available 164 ACL policies. Note that ACL replication is rate limited so the indexes may lag behind 165 the primary datacenter. 166 167- `ReplicatedTokenIndex` - The last token index that was successfully replicated. 168 This index can be compared with the value of the `X-Consul-Index` header returned 169 by the [`/v1/acl/tokens`](/api/acl/tokens.html#list) endpoint to determine 170 if the replication process has gotten all available ACL tokens. Note that ACL 171 replication is rate limited so the indexes may lag behind the primary 172 datacenter. 173 174- `LastSuccess` - The UTC time of the last successful sync operation. Since ACL 175 replication is done with a blocking query, this may not update for up to 5 176 minutes if there have been no ACL changes to replicate. A zero value of 177 "0001-01-01T00:00:00Z" will be present if no sync has been successful. 178 179- `LastError` - The UTC time of the last error encountered during a sync 180 operation. If this time is later than `LastSuccess`, you can assume the 181 replication process is not in a good state. A zero value of 182 "0001-01-01T00:00:00Z" will be present if no sync has resulted in an error. 183 184## Translate Rules 185 186-> **Deprecated** - This endpoint was introduced in Consul 1.4.0 for migration from the previous ACL system. It 187will be removed in a future major Consul version when support for legacy ACLs is removed. 188 189This endpoint translates the legacy rule syntax into the latest syntax. It is intended 190to be used by operators managing Consul's ACLs and performing legacy token to new policy 191migrations. 192 193| Method | Path | Produces | 194| ------ | --------------------------- | -------------------------- | 195| `POST` | `/acl/rules/translate` | `text/plain` | 196 197The table below shows this endpoint's support for 198[blocking queries](/api/features/blocking.html), 199[consistency modes](/api/features/consistency.html), 200[agent caching](/api/features/caching.html), and 201[required ACLs](/api/index.html#authentication). 202 203| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 204| ---------------- | ----------------- | ------------- | ------------ | 205| `NO` | `none` | `none` | `acl:read` | 206 207### Sample Payload 208 209```text 210agent "" { 211 policy = "read" 212} 213``` 214 215### Sample Request 216 217```text 218$ curl -X POST -d @rules.hcl http://127.0.0.1:8500/v1/acl/rules/translate 219``` 220 221### Sample Response 222 223```text 224agent_prefix "" { 225 policy = "read" 226} 227``` 228 229## Translate a Legacy Token's Rules 230 231-> **Deprecated** - This endpoint was introduced in Consul 1.4.0 for migration from the previous ACL system.. It 232will be removed in a future major Consul version when support for legacy ACLs is removed. 233 234This endpoint translates the legacy rules embedded within a legacy ACL into the latest 235syntax. It is intended to be used by operators managing Consul's ACLs and performing 236legacy token to new policy migrations. Note that this API requires the auto-generated 237Accessor ID of the legacy token. This ID can be retrieved using the 238[`/v1/acl/token/self`](/api/acl/tokens.html#self) endpoint. 239 240| Method | Path | Produces | 241| ------ | ----------------------------------- | -------------------------- | 242| `GET` | `/acl/rules/translate/:accessor_id` | `text/plain` | 243 244The table below shows this endpoint's support for 245[blocking queries](/api/features/blocking.html), 246[consistency modes](/api/features/consistency.html), 247[agent caching](/api/features/caching.html), and 248[required ACLs](/api/index.html#authentication). 249 250| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 251| ---------------- | ----------------- | ------------- | ------------ | 252| `NO` | `none` | `none` | `acl:read` | 253 254### Sample Request 255 256```text 257$ curl -X GET http://127.0.0.1:8500/v1/acl/rules/translate/4f48f7e6-9359-4890-8e67-6144a962b0a5 258``` 259 260### Sample Response 261 262```text 263agent_prefix "" { 264 policy = "read" 265} 266``` 267 268## Login to Auth Method 269 270This endpoint was added in Consul 1.5.0 and is used to exchange an [auth 271method](/docs/acl/acl-auth-methods.html) bearer token for a newly-created 272Consul ACL token. 273 274| Method | Path | Produces | 275| ------ | ---------------------------- | -------------------------- | 276| `POST` | `/acl/login` | `application/json` | 277 278The table below shows this endpoint's support for 279[blocking queries](/api/features/blocking.html), 280[consistency modes](/api/features/consistency.html), 281[agent caching](/api/features/caching.html), and 282[required ACLs](/api/index.html#authentication). 283 284| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 285| ---------------- | ----------------- | ------------- | ------------ | 286| `NO` | `none` | `none` | `none` | 287 288-> **Note** - To use the login process to create tokens in any connected 289secondary datacenter, [ACL 290replication](/docs/agent/options.html#acl_enable_token_replication) must be 291enabled. Login requires the ability to create local tokens which is restricted 292to the primary datacenter and any secondary datacenters with ACL token 293replication enabled. 294 295 296### Parameters 297 298- `AuthMethod` `(string: <required>)` - The name of the auth method to use for login. 299 300- `BearerToken` `(string: <required>)` - The bearer token to present to the 301 auth method during login for authentication purposes. For the Kubernetes auth 302 method this is a [Service Account Token 303 (JWT)](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#service-account-tokens). 304 305- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata 306 linked to the token. Can be useful to track origins. 307 308- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of 309 the Auth Method to use for Login. If not provided in the JSON body, the value of 310 the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. 311 If not provided at all, the namespace will be inherited from the request's ACL 312 token, or will default to the `default` namespace. Added in Consul 1.7.0. 313 314### Sample Payload 315 316```json 317{ 318 "AuthMethod": "minikube", 319 "BearerToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..." 320} 321``` 322 323### Sample Request 324 325```sh 326$ curl \ 327 --request POST \ 328 --data @payload.json \ 329 http://127.0.0.1:8500/v1/acl/login 330``` 331 332### Sample Response 333 334```json 335{ 336 "AccessorID": "926e2bd2-b344-d91b-0c83-ae89f372cd9b", 337 "SecretID": "b78d37c7-0ca7-5f4d-99ee-6d9975ce4586", 338 "Description": "token created via login", 339 "Roles": [ 340 { 341 "ID": "3356c67c-5535-403a-ad79-c1d5f9df8fc7", 342 "Name": "demo" 343 } 344 ], 345 "ServiceIdentities": [ 346 { 347 "ServiceName": "example" 348 } 349 ], 350 "Local": true, 351 "AuthMethod": "minikube", 352 "CreateTime": "2019-04-29T10:08:08.404370762-05:00", 353 "Hash": "nLimyD+7l6miiHEBmN/tvCelAmE/SbIXxcnTzG3pbGY=", 354 "CreateIndex": 36, 355 "ModifyIndex": 36 356} 357``` 358 359## Logout from Auth Method 360 361This endpoint was added in Consul 1.5.0 and is used to destroy a token created 362via the [login endpoint](#login-to-auth-method). The token deleted is specified 363with the `X-Consul-Token` header or the `token` query parameter. 364 365| Method | Path | Produces | 366| ------ | ---------------------------- | -------------------------- | 367| `POST` | `/acl/logout` | `application/json` | 368 369The table below shows this endpoint's support for 370[blocking queries](/api/features/blocking.html), 371[consistency modes](/api/features/consistency.html), 372[agent caching](/api/features/caching.html), and 373[required ACLs](/api/index.html#authentication). 374 375| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 376| ---------------- | ----------------- | ------------- | ------------ | 377| `NO` | `none` | `none` | `none` | 378 379-> **Note** - This endpoint requires no specific privileges as it is just 380deleting a token for which you already must possess its secret. 381 382### Sample Request 383 384```sh 385$ curl \ 386 -H "X-Consul-Token: b78d37c7-0ca7-5f4d-99ee-6d9975ce4586" \ 387 --request POST \ 388 http://127.0.0.1:8500/v1/acl/logout 389``` 390