github.com/quite/nomad@v0.8.6/website/source/api/acl-tokens.html.md (about) 1 --- 2 layout: api 3 page_title: ACL Tokens - HTTP API 4 sidebar_current: api-acl-tokens 5 description: |- 6 The /acl/token/ endpoints are used to configure and manage ACL tokens. 7 --- 8 9 # ACL Tokens HTTP API 10 11 The `/acl/bootstrap`, `/acl/tokens`, and `/acl/token/` endpoints are used to manage ACL tokens. 12 For more details about ACLs, please see the [ACL Guide](/guides/acl.html). 13 14 ## Bootstrap Token 15 16 This endpoint is used to bootstrap the ACL system and provide the initial management token. 17 This request is always forwarded to the authoritative region. It can only be invoked once 18 until a [bootstrap reset](/guides/acl.html#reseting-acl-bootstrap) is performed. 19 20 | Method | Path | Produces | 21 | ------ | ---------------------------- | -------------------------- | 22 | `POST` | `/acl/bootstrap` | `application/json` | 23 24 The table below shows this endpoint's support for 25 [blocking queries](/api/index.html#blocking-queries) and 26 [required ACLs](/api/index.html#acls). 27 28 | Blocking Queries | ACL Required | 29 | ---------------- | ------------------ | 30 | `NO` | `none` | 31 32 ### Sample Request 33 34 ```text 35 $ curl \ 36 --request POST \ 37 https://localhost:4646/v1/acl/bootstrap 38 ``` 39 40 ### Sample Response 41 42 ```json 43 { 44 "AccessorID":"b780e702-98ce-521f-2e5f-c6b87de05b24", 45 "SecretID":"3f4a0fcd-7c42-773c-25db-2d31ba0c05fe", 46 "Name":"Bootstrap Token", 47 "Type":"management", 48 "Policies":null, 49 "Global":true, 50 "CreateTime":"2017-08-23T22:47:14.695408057Z", 51 "CreateIndex":7, 52 "ModifyIndex":7 53 } 54 ``` 55 56 ## List Tokens 57 58 This endpoint lists all ACL tokens. This lists the local tokens and the global 59 tokens which have been replicated to the region, and may lag behind the authoritative region. 60 61 | Method | Path | Produces | 62 | ------ | ---------------------------- | -------------------------- | 63 | `GET` | `/acl/tokens` | `application/json` | 64 65 The table below shows this endpoint's support for 66 [blocking queries](/api/index.html#blocking-queries), [consistency modes](/api/index.html#consistency-modes) and 67 [required ACLs](/api/index.html#acls). 68 69 | Blocking Queries | Consistency Modes | ACL Required | 70 | ---------------- | ----------------- | ------------ | 71 | `YES` | `all` | `management` | 72 73 74 ### Sample Request 75 76 ```text 77 $ curl \ 78 https://localhost:4646/v1/acl/tokens 79 ``` 80 81 ### Sample Response 82 83 ```json 84 [ 85 { 86 "AccessorID": "b780e702-98ce-521f-2e5f-c6b87de05b24", 87 "Name": "Bootstrap Token", 88 "Type": "management", 89 "Policies": null, 90 "Global": true, 91 "CreateTime": "2017-08-23T22:47:14.695408057Z", 92 "CreateIndex": 7, 93 "ModifyIndex": 7 94 } 95 ] 96 ``` 97 98 ## Create Token 99 100 This endpoint creates an ACL Token. If the token is a global token, the request 101 is forwarded to the authoritative region. 102 103 | Method | Path | Produces | 104 | ------ | ---------------------------- | -------------------------- | 105 | `POST` | `/acl/token` | `application/json` | 106 107 The table below shows this endpoint's support for 108 [blocking queries](/api/index.html#blocking-queries) and 109 [required ACLs](/api/index.html#acls). 110 111 | Blocking Queries | ACL Required | 112 | ---------------- | ------------------ | 113 | `NO` | `management` | 114 115 ### Parameters 116 117 - `Name` `(string: <optional>)` - Specifies the human readable name of the token. 118 119 - `Type` `(string: <required>)` - Specifies the type of token. Must be either `client` or `management`. 120 121 - `Policies` `(array<string>: <required>)` - Must be null or blank for `management` type tokens, otherwise must specify at least one policy for `client` type tokens. 122 123 - `Global` `(bool: <optional>)` - If true, indicates this token should be replicated globally to all regions. Otherwise, this token is created local to the target region. 124 125 ### Sample Payload 126 127 ```json 128 { 129 "Name": "Readonly token", 130 "Type": "client", 131 "Policies": ["readonly"], 132 "Global": false 133 } 134 ``` 135 136 ### Sample Request 137 138 ```text 139 $ curl \ 140 --request POST \ 141 --data @payload.json \ 142 https://localhost:4646/v1/acl/token 143 ``` 144 145 ### Sample Response 146 147 ```json 148 { 149 "AccessorID": "aa534e09-6a07-0a45-2295-a7f77063d429", 150 "SecretID": "8176afd3-772d-0b71-8f85-7fa5d903e9d4", 151 "Name": "Readonly token", 152 "Type": "client", 153 "Policies": [ 154 "readonly" 155 ], 156 "Global": false, 157 "CreateTime": "2017-08-23T23:25:41.429154233Z", 158 "CreateIndex": 52, 159 "ModifyIndex": 52 160 } 161 ``` 162 163 ## Update Token 164 165 This endpoint updates an existing ACL Token. If the token is a global token, the request 166 is forwarded to the authoritative region. Note that a token cannot be switched from global 167 to local or visa versa. 168 169 | Method | Path | Produces | 170 | ------ | ---------------------------- | -------------------------- | 171 | `POST` | `/acl/token/:accessor_id` | `application/json` | 172 173 The table below shows this endpoint's support for 174 [blocking queries](/api/index.html#blocking-queries) and 175 [required ACLs](/api/index.html#acls). 176 177 | Blocking Queries | ACL Required | 178 | ---------------- | ------------------ | 179 | `NO` | `management` | 180 181 ### Parameters 182 183 - `AccessorID` `(string: <required>)` - Specifies the token (by accessor) that is being updated. Must match payload body and request path. 184 185 - `Name` `(string: <optional>)` - Specifies the human readable name of the token. 186 187 - `Type` `(string: <required>)` - Specifies the type of token. Must be either `client` or `management`. 188 189 - `Policies` `(array<string>: <required>)` - Must be null or blank for `management` type tokens, otherwise must specify at least one policy for `client` type tokens. 190 191 ### Sample Payload 192 193 ```json 194 { 195 "AccessorID": "aa534e09-6a07-0a45-2295-a7f77063d429", 196 "Name": "Read-write token", 197 "Type": "client", 198 "Policies": ["readwrite"], 199 } 200 ``` 201 202 ### Sample Request 203 204 ```text 205 $ curl \ 206 --request POST \ 207 --data @payload.json \ 208 https://localhost:4646/v1/acl/token/aa534e09-6a07-0a45-2295-a7f77063d429 209 ``` 210 211 ### Sample Response 212 213 ```json 214 { 215 "AccessorID": "aa534e09-6a07-0a45-2295-a7f77063d429", 216 "SecretID": "8176afd3-772d-0b71-8f85-7fa5d903e9d4", 217 "Name": "Read-write token", 218 "Type": "client", 219 "Policies": [ 220 "readwrite" 221 ], 222 "Global": false, 223 "CreateTime": "2017-08-23T23:25:41.429154233Z", 224 "CreateIndex": 52, 225 "ModifyIndex": 64 226 } 227 ``` 228 229 ## Read Token 230 231 This endpoint reads an ACL token with the given accessor. If the token is a global token 232 which has been replicated to the region it may lag behind the authoritative region. 233 234 | Method | Path | Produces | 235 | ------ | ---------------------------- | -------------------------- | 236 | `GET` | `/acl/token/:accessor_id` | `application/json` | 237 238 The table below shows this endpoint's support for 239 [blocking queries](/api/index.html#blocking-queries), [consistency modes](/api/index.html#consistency-modes) and 240 [required ACLs](/api/index.html#acls). 241 242 | Blocking Queries | Consistency Modes | ACL Required | 243 | ---------------- | ----------------- | ------------ | 244 | `YES` | `all` | `management` or a SecretID matching the AccessorID | 245 246 ### Sample Request 247 248 ```text 249 $ curl \ 250 https://localhost:4646/v1/acl/token/aa534e09-6a07-0a45-2295-a7f77063d429 251 ``` 252 253 ### Sample Response 254 255 ```json 256 { 257 "AccessorID": "aa534e09-6a07-0a45-2295-a7f77063d429", 258 "SecretID": "8176afd3-772d-0b71-8f85-7fa5d903e9d4", 259 "Name": "Read-write token", 260 "Type": "client", 261 "Policies": [ 262 "readwrite" 263 ], 264 "Global": false, 265 "CreateTime": "2017-08-23T23:25:41.429154233Z", 266 "CreateIndex": 52, 267 "ModifyIndex": 64 268 } 269 ``` 270 271 ## Read Self Token 272 273 This endpoint reads the ACL token given by the passed SecretID. If the token is a global token 274 which has been replicated to the region it may lag behind the authoritative region. 275 276 | Method | Path | Produces | 277 | ------ | ---------------------------- | -------------------------- | 278 | `GET` | `/acl/token/self` | `application/json` | 279 280 The table below shows this endpoint's support for 281 [blocking queries](/api/index.html#blocking-queries), [consistency modes](/api/index.html#consistency-modes) and 282 [required ACLs](/api/index.html#acls). 283 284 | Blocking Queries | Consistency Modes | ACL Required | 285 | ---------------- | ----------------- | ------------ | 286 | `YES` | `all` | Any valid ACL token | 287 288 ### Sample Request 289 290 ```text 291 $ curl \ 292 --header "X-Nomad-Token: 8176afd3-772d-0b71-8f85-7fa5d903e9d4" \ 293 https://localhost:4646/v1/acl/token/self 294 ``` 295 296 ### Sample Response 297 298 ```json 299 { 300 "AccessorID": "aa534e09-6a07-0a45-2295-a7f77063d429", 301 "SecretID": "8176afd3-772d-0b71-8f85-7fa5d903e9d4", 302 "Name": "Read-write token", 303 "Type": "client", 304 "Policies": [ 305 "readwrite" 306 ], 307 "Global": false, 308 "CreateTime": "2017-08-23T23:25:41.429154233Z", 309 "CreateIndex": 52, 310 "ModifyIndex": 64 311 } 312 ``` 313 314 ## Delete Token 315 316 This endpoint deletes the ACL token by accessor. This request is forwarded to the 317 authoritative region for global tokens. 318 319 | Method | Path | Produces | 320 | -------- | ---------------------------- | -------------------------- | 321 | `DELETE` | `/acl/token/:accessor_id` | `(empty body)` | 322 323 The table below shows this endpoint's support for 324 [blocking queries](/api/index.html#blocking-queries) and 325 [required ACLs](/api/index.html#acls). 326 327 | Blocking Queries | ACL Required | 328 | ---------------- | ------------- | 329 | `NO` | `management` | 330 331 ### Parameters 332 333 - `accessor_id` `(string: <required>)` - Specifies the ACL token accessor ID. 334 335 ### Sample Request 336 337 ```text 338 $ curl \ 339 --request DELETE \ 340 https://localhost:4646/v1/acl/token/aa534e09-6a07-0a45-2295-a7f77063d429 341 ``` 342