1--- 2layout: api 3page_title: ACLs - HTTP API 4description: The /acl endpoints manage the Consul's ACL system. 5--- 6 7# ACL HTTP API 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). 10 11The `/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) and [policies](/api/acl/policies) with the `/acl` endpoints. 12 13For more information on how to setup ACLs, please check 14the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production). 15 16## Bootstrap ACLs 17 18This endpoint does a special one-time bootstrap of the ACL system, making the first 19management token if the [`acl.tokens.master`](/docs/agent/options#acl_tokens_master) 20configuration entry is not specified in the Consul server configuration and if the 21cluster has not been bootstrapped previously. This is available in Consul 0.9.1 and later, 22and requires all Consul servers to be upgraded in order to operate. 23 24This provides a mechanism to bootstrap ACLs without having any secrets present in Consul's 25configuration files. 26 27| Method | Path | Produces | 28| ------ | ---------------- | ------------------ | 29| `PUT` | `/acl/bootstrap` | `application/json` | 30 31The table below shows this endpoint's support for 32[blocking queries](/api/features/blocking), 33[consistency modes](/api/features/consistency), 34[agent caching](/api/features/caching), and 35[required ACLs](/api#authentication). 36 37| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 38| ---------------- | ----------------- | ------------- | ------------ | 39| `NO` | `none` | `none` | `none` | 40 41### Sample Request 42 43```shell-session 44$ curl \ 45 --request PUT \ 46 http://127.0.0.1:8500/v1/acl/bootstrap 47``` 48 49### Sample Response 50 51-> **Deprecated** - The `ID` field in the response is for legacy compatibility and is a copy of the `SecretID` field. New 52applications should ignore the `ID` field as it may be removed in a future major Consul version. 53 54```json 55{ 56 "ID": "527347d3-9653-07dc-adc0-598b8f2b0f4d", 57 "AccessorID": "b5b1a918-50bc-fc46-dec2-d481359da4e3", 58 "SecretID": "527347d3-9653-07dc-adc0-598b8f2b0f4d", 59 "Description": "Bootstrap Token (Global Management)", 60 "Policies": [ 61 { 62 "ID": "00000000-0000-0000-0000-000000000001", 63 "Name": "global-management" 64 } 65 ], 66 "Local": false, 67 "CreateTime": "2018-10-24T10:34:20.843397-04:00", 68 "Hash": "oyrov6+GFLjo/KZAfqgxF/X4J/3LX0435DOBy9V22I0=", 69 "CreateIndex": 12, 70 "ModifyIndex": 12 71} 72``` 73 74You can detect if something has interfered with the ACL bootstrapping process by 75checking the response code. A 200 response means that the bootstrap was a success, and 76a 403 means that the cluster has already been bootstrapped, at which point you should 77consider the cluster in a potentially compromised state. 78 79The returned token will have unrestricted privileges to manage all details of the system. 80It can then be used to further configure the ACL system. Please check the 81[ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) for more details. 82 83## Check ACL Replication 84 85This endpoint returns the status of the ACL replication processes in the 86datacenter. This is intended to be used by operators or by automation checking 87to discover the health of ACL replication. 88 89Please check the [ACL Replication tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-replication-multiple-datacenters) 90for more details. 91 92| Method | Path | Produces | 93| ------ | ------------------ | ------------------ | 94| `GET` | `/acl/replication` | `application/json` | 95 96The table below shows this endpoint's support for 97[blocking queries](/api/features/blocking), 98[consistency modes](/api/features/consistency), 99[agent caching](/api/features/caching), and 100[required ACLs](/api#authentication). 101 102| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 103| ---------------- | ----------------- | ------------- | ------------ | 104| `NO` | `consistent` | `none` | `none` | 105 106### Parameters 107 108- `dc` `(string: "")` - Specifies the datacenter to query. This will default to 109 the datacenter of the agent being queried. This is specified as part of the 110 URL as a query parameter. 111 112### Sample Request 113 114```shell-session 115$ curl \ 116 --request GET \ 117 http://127.0.0.1:8500/v1/acl/replication 118``` 119 120### Sample Response 121 122```json 123{ 124 "Enabled": true, 125 "Running": true, 126 "SourceDatacenter": "dc1", 127 "ReplicationType": "tokens", 128 "ReplicatedIndex": 1976, 129 "ReplicatedTokenIndex": 2018, 130 "LastSuccess": "2018-11-03T06:28:58Z", 131 "LastError": "2016-11-03T06:28:28Z" 132} 133``` 134 135- `Enabled` - Reports whether ACL replication is enabled for the datacenter. 136 137- `Running` - Reports whether the ACL replication process is running. The process 138 may take approximately 60 seconds to begin running after a leader election 139 occurs. 140 141- `SourceDatacenter` - The authoritative ACL datacenter that ACLs are being 142 replicated from and will match the 143 [`primary_datacenter`](/docs/agent/options#primary_datacenter) configuration. 144 145- `ReplicationType` - The type of replication that is currently in use. 146 147 - `legacy` - ACL replication is in legacy mode and is replicating legacy ACL tokens. 148 149 - `policies` - ACL replication is only replicating policies as token replication 150 is disabled. 151 152 - `tokens` - ACL replication is replicating both policies and tokens. 153 154- `ReplicatedIndex` - The last index that was successfully replicated. Which data 155 the replicated index refers to depends on the replication type. For `legacy` 156 replication this can be compared with the value of the `X-Consul-Index` header 157 returned by the [`/v1/acl/list`](/api/acl/legacy#list-acls) endpoint to 158 determine if the replication process has gotten all available ACLs. When in either 159 `tokens` or `policies` mode, this index can be compared with the value of the 160 `X-Consul-Index` header returned by the [`/v1/acl/policies`](/api/acl/policies#list-policies) 161 endpoint to determine if the policy replication process has gotten all available 162 ACL policies. Note that ACL replication is rate limited so the indexes may lag behind 163 the primary datacenter. 164 165- `ReplicatedTokenIndex` - The last token index that was successfully replicated. 166 This index can be compared with the value of the `X-Consul-Index` header returned 167 by the [`/v1/acl/tokens`](/api/acl/tokens#list-tokens) endpoint to determine 168 if the replication process has gotten all available ACL tokens. Note that ACL 169 replication is rate limited so the indexes may lag behind the primary 170 datacenter. 171 172- `LastSuccess` - The UTC time of the last successful sync operation. Since ACL 173 replication is done with a blocking query, this may not update for up to 5 174 minutes if there have been no ACL changes to replicate. A zero value of 175 "0001-01-01T00:00:00Z" will be present if no sync has been successful. 176 177- `LastError` - The UTC time of the last error encountered during a sync 178 operation. If this time is later than `LastSuccess`, you can assume the 179 replication process is not in a good state. A zero value of 180 "0001-01-01T00:00:00Z" will be present if no sync has resulted in an error. 181 182## Translate Rules 183 184-> **Deprecated** - This endpoint was introduced in Consul 1.4.0 for migration from the previous ACL system. It 185will be removed in a future major Consul version when support for legacy ACLs is removed. 186 187This endpoint translates the legacy rule syntax into the latest syntax. It is intended 188to be used by operators managing Consul's ACLs and performing legacy token to new policy 189migrations. 190 191| Method | Path | Produces | 192| ------ | ---------------------- | ------------ | 193| `POST` | `/acl/rules/translate` | `text/plain` | 194 195The table below shows this endpoint's support for 196[blocking queries](/api/features/blocking), 197[consistency modes](/api/features/consistency), 198[agent caching](/api/features/caching), and 199[required ACLs](/api#authentication). 200 201| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 202| ---------------- | ----------------- | ------------- | ------------ | 203| `NO` | `none` | `none` | `acl:read` | 204 205### Sample Payload 206 207```hcl 208agent "" { 209 policy = "read" 210} 211``` 212 213### Sample Request 214 215```shell-session 216$ curl -X POST -d @rules.hcl http://127.0.0.1:8500/v1/acl/rules/translate 217``` 218 219### Sample Response 220 221```hcl 222agent_prefix "" { 223 policy = "read" 224} 225``` 226 227## Translate a Legacy Token's Rules 228 229-> **Deprecated** - This endpoint was introduced in Consul 1.4.0 for migration from the previous ACL system.. It 230will be removed in a future major Consul version when support for legacy ACLs is removed. 231 232This endpoint translates the legacy rules embedded within a legacy ACL into the latest 233syntax. It is intended to be used by operators managing Consul's ACLs and performing 234legacy token to new policy migrations. Note that this API requires the auto-generated 235Accessor ID of the legacy token. This ID can be retrieved using the 236[`/v1/acl/token/self`](/api/acl/tokens#read-self-token) endpoint. 237 238| Method | Path | Produces | 239| ------ | ----------------------------------- | ------------ | 240| `GET` | `/acl/rules/translate/:accessor_id` | `text/plain` | 241 242The table below shows this endpoint's support for 243[blocking queries](/api/features/blocking), 244[consistency modes](/api/features/consistency), 245[agent caching](/api/features/caching), and 246[required ACLs](/api#authentication). 247 248| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 249| ---------------- | ----------------- | ------------- | ------------ | 250| `NO` | `none` | `none` | `acl:read` | 251 252### Sample Request 253 254```shell-session 255$ curl -X GET http://127.0.0.1:8500/v1/acl/rules/translate/4f48f7e6-9359-4890-8e67-6144a962b0a5 256``` 257 258### Sample Response 259 260```hcl 261agent_prefix "" { 262 policy = "read" 263} 264``` 265 266## Login to Auth Method 267 268This endpoint was added in Consul 1.5.0 and is used to exchange an [auth 269method](/docs/acl/auth-methods) bearer token for a newly-created 270Consul ACL token. 271 272| Method | Path | Produces | 273| ------ | ------------ | ------------------ | 274| `POST` | `/acl/login` | `application/json` | 275 276The table below shows this endpoint's support for 277[blocking queries](/api/features/blocking), 278[consistency modes](/api/features/consistency), 279[agent caching](/api/features/caching), and 280[required ACLs](/api#authentication). 281 282| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 283| ---------------- | ----------------- | ------------- | ------------ | 284| `NO` | `none` | `none` | `none` | 285 286-> **Note** - To use the login process to create tokens in any connected 287secondary datacenter, [ACL 288replication](/docs/agent/options#acl_enable_token_replication) must be 289enabled. Login requires the ability to create local tokens which is restricted 290to the primary datacenter and any secondary datacenters with ACL token 291replication enabled. 292 293### Parameters 294 295- `AuthMethod` `(string: <required>)` - The name of the auth method to use for login. 296 297- `BearerToken` `(string: <required>)` - The bearer token to present to the 298 auth method during login for authentication purposes. For the Kubernetes auth 299 method this is a [Service Account Token 300 (JWT)](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#service-account-tokens). 301 302- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata 303 linked to the token. Can be useful to track origins. 304 305- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of 306 the Auth Method to use for Login. If not provided in the JSON body, the value of 307 the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. 308 If not provided, the namespace will be inherited from the request's ACL 309 token, or will default to the `default` namespace. Added in Consul 1.7.0. 310 311### Sample Payload 312 313```json 314{ 315 "AuthMethod": "minikube", 316 "BearerToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..." 317} 318``` 319 320### Sample Request 321 322```shell-session 323$ curl \ 324 --request POST \ 325 --data @payload.json \ 326 http://127.0.0.1:8500/v1/acl/login 327``` 328 329### Sample Response 330 331```json 332{ 333 "AccessorID": "926e2bd2-b344-d91b-0c83-ae89f372cd9b", 334 "SecretID": "b78d37c7-0ca7-5f4d-99ee-6d9975ce4586", 335 "Description": "token created via login", 336 "Roles": [ 337 { 338 "ID": "3356c67c-5535-403a-ad79-c1d5f9df8fc7", 339 "Name": "demo" 340 } 341 ], 342 "ServiceIdentities": [ 343 { 344 "ServiceName": "example" 345 } 346 ], 347 "Local": true, 348 "AuthMethod": "minikube", 349 "CreateTime": "2019-04-29T10:08:08.404370762-05:00", 350 "Hash": "nLimyD+7l6miiHEBmN/tvCelAmE/SbIXxcnTzG3pbGY=", 351 "CreateIndex": 36, 352 "ModifyIndex": 36 353} 354``` 355 356## Logout from Auth Method 357 358This endpoint was added in Consul 1.5.0 and is used to destroy a token created 359via the [login endpoint](#login-to-auth-method). The token deleted is specified 360with the `X-Consul-Token` header or the `token` query parameter. 361 362| Method | Path | Produces | 363| ------ | ------------- | ------------------ | 364| `POST` | `/acl/logout` | `application/json` | 365 366The table below shows this endpoint's support for 367[blocking queries](/api/features/blocking), 368[consistency modes](/api/features/consistency), 369[agent caching](/api/features/caching), and 370[required ACLs](/api#authentication). 371 372| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 373| ---------------- | ----------------- | ------------- | ------------ | 374| `NO` | `none` | `none` | `none` | 375 376-> **Note** - This endpoint requires no specific privileges as it is just 377deleting a token for which you already must possess its secret. 378 379### Sample Request 380 381```shell-session 382$ curl \ 383 -H "X-Consul-Token: b78d37c7-0ca7-5f4d-99ee-6d9975ce4586" \ 384 --request POST \ 385 http://127.0.0.1:8500/v1/acl/logout 386``` 387 388## OIDC Authorization URL Request 389 390<EnterpriseAlert> 391 {' '} 392 This is an enterprise only endpoint. 393</EnterpriseAlert> 394 395This endpoint was added in Consul 1.8.0 and is used to obtain an authorization 396URL from Consul to start an [OIDC login flow](/docs/acl/auth-methods/oidc). 397 398| Method | Path | Produces | 399| ------ | -------------------- | ------------------ | 400| `POST` | `/acl/oidc/auth-url` | `application/json` | 401 402The table below shows this endpoint's support for 403[blocking queries](/api/features/blocking), 404[consistency modes](/api/features/consistency), 405[agent caching](/api/features/caching), and 406[required ACLs](/api#authentication). 407 408| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 409| ---------------- | ----------------- | ------------- | ------------ | 410| `NO` | `none` | `none` | `none` | 411 412-> **Note** - To use the login process to create tokens in any connected 413secondary datacenter, [ACL 414replication](/docs/agent/options#acl_enable_token_replication) must be 415enabled. Login requires the ability to create local tokens which is restricted 416to the primary datacenter and any secondary datacenters with ACL token 417replication enabled. 418 419### Parameters 420 421- `AuthMethod` `(string: <required>)` - The name of the auth method to use for 422 login. This must be of type [`oidc`](/docs/acl/auth-methods/oidc). 423 424- `RedirectURI` `(string: <required>)` - See [Redirect 425 URIs](/docs/acl/auth-methods/oidc#redirect-uris) for more information. 426 427- `ClientNonce` `(string: "")` - Optional client-provided nonce that must match 428 during callback, if present. 429 430- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata 431 linked to the token. Can be useful to track origins. 432 433- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of 434 the Auth Method to use for Login. If not provided in the JSON body, the value of 435 the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. 436 If not provided, the namespace will be inherited from the request's ACL 437 token, or will default to the `default` namespace. 438 439 This must match the namespace provided on the [OIDC Callback](#oidc-callback). 440 441### Sample Payload 442 443```json 444{ 445 "AuthMethod": "auth0", 446 "RedirectURI": "http://localhost:8550/oidc/callback" 447} 448``` 449 450### Sample Request 451 452```shell-session 453$ curl \ 454 --request POST \ 455 --data @payload.json \ 456 http://127.0.0.1:8500/v1/acl/oidc/auth-url 457``` 458 459### Sample Response 460 461```json 462{ 463 "AuthURL": "https://myprovider.com/authorize?client_id=..." 464} 465``` 466 467## OIDC Callback 468 469<EnterpriseAlert> 470 {' '} 471 This is an enterprise only endpoint. 472</EnterpriseAlert> 473 474This endpoint was added in Consul 1.8.0 and is used to exchange an OIDC 475authorization code for an OIDC ID Token. The ID token will in turn be exchanged 476for a newly-created Consul ACL token. 477 478| Method | Path | Produces | 479| ------ | -------------------- | ------------------ | 480| `POST` | `/acl/oidc/callback` | `application/json` | 481 482The table below shows this endpoint's support for 483[blocking queries](/api/features/blocking), 484[consistency modes](/api/features/consistency), 485[agent caching](/api/features/caching), and 486[required ACLs](/api#authentication). 487 488| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 489| ---------------- | ----------------- | ------------- | ------------ | 490| `NO` | `none` | `none` | `none` | 491 492-> **Note** - To use the login process to create tokens in any connected 493secondary datacenter, [ACL 494replication](/docs/agent/options#acl_enable_token_replication) must be 495enabled. Login requires the ability to create local tokens which is restricted 496to the primary datacenter and any secondary datacenters with ACL token 497replication enabled. 498 499### Parameters 500 501- `AuthMethod` `(string: <required>)` - The name of the auth method to use for 502 login. This must be of type [`oidc`](/docs/acl/auth-methods/oidc). 503 504- `State` `(string: <required>)` - Opaque state ID that is part of the 505 Authorization URL and will be included in the the redirect following 506 successful authentication on the provider. 507 508- `Code` `(string: <required>)` - Provider-generated authorization code that 509 Consul will exchange for an ID token. 510 511- `ClientNonce` `(string: "")` - Optional client-provided nonce that must match 512 the one provided in the auth url request, if present. 513 514- `Meta` `(map<string|string>: nil)` - Specifies arbitrary KV metadata 515 linked to the token. Can be useful to track origins. 516 517- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of 518 the Auth Method to use for Login. If not provided in the JSON body, the value of 519 the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. 520 If not provided, the namespace will be inherited from the request's ACL 521 token, or will default to the `default` namespace. 522 523 This must match the namespace provided on the [OIDC Callback](#oidc-callback). 524 525### Sample Payload 526 527```json 528{ 529 "AuthMethod": "auth0", 530 "State": "aa3f1903c2f5eac666e6f92e804cf7fc0ff1d15b", 531 "Code": "dn0u9oM9WegYBEnp" 532} 533``` 534 535### Sample Request 536 537```shell-session 538$ curl \ 539 --request POST \ 540 --data @payload.json \ 541 http://127.0.0.1:8500/v1/acl/oidc/callback 542``` 543 544### Sample Response 545 546```json 547{ 548 "AccessorID": "926e2bd2-b344-d91b-0c83-ae89f372cd9b", 549 "SecretID": "b78d37c7-0ca7-5f4d-99ee-6d9975ce4586", 550 "Description": "token created via OIDC login", 551 "Roles": [ 552 { 553 "ID": "3356c67c-5535-403a-ad79-c1d5f9df8fc7", 554 "Name": "demo" 555 } 556 ], 557 "ServiceIdentities": [ 558 { 559 "ServiceName": "example" 560 } 561 ], 562 "Local": true, 563 "AuthMethod": "auth0", 564 "CreateTime": "2019-04-29T10:08:08.404370762-05:00", 565 "Hash": "nLimyD+7l6miiHEBmN/tvCelAmE/SbIXxcnTzG3pbGY=", 566 "CreateIndex": 36, 567 "ModifyIndex": 36 568} 569``` 570