489 lines
14 KiB
Plaintext
489 lines
14 KiB
Plaintext
---
|
|
layout: api
|
|
page_title: ACL Tokens - HTTP API
|
|
description: The /acl/token/ endpoints are used to configure and manage ACL tokens.
|
|
---
|
|
|
|
# ACL Tokens HTTP API
|
|
|
|
The `/acl/bootstrap`, `/acl/tokens`, and `/acl/token/` endpoints are used to manage ACL tokens.
|
|
For more details about ACLs, please see the [ACL Guide](https://learn.hashicorp.com/collections/nomad/access-control).
|
|
|
|
## Bootstrap Token
|
|
|
|
This endpoint is used to bootstrap the ACL system and provide the initial management token.
|
|
An operator created token can be provided in the body of the request to bootstrap the cluster
|
|
if required. If no header is provided the cluster will return a generated management token.
|
|
The provided token should be presented in a UUID format.
|
|
This request is always forwarded to the authoritative region. It can only be invoked once
|
|
until a [bootstrap reset](https://learn.hashicorp.com/tutorials/nomad/access-control-bootstrap#re-bootstrap-acl-system) is performed.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ---------------- | ------------------ |
|
|
| `POST` | `/acl/bootstrap` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/api-docs#blocking-queries) and
|
|
[required ACLs](/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | ------------ |
|
|
| `NO` | `none` |
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
https://localhost:4646/v1/acl/bootstrap
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"AccessorID": "b780e702-98ce-521f-2e5f-c6b87de05b24",
|
|
"SecretID": "3f4a0fcd-7c42-773c-25db-2d31ba0c05fe",
|
|
"Name": "Bootstrap Token",
|
|
"Type": "management",
|
|
"Policies": null,
|
|
"Global": true,
|
|
"CreateTime": "2017-08-23T22:47:14.695408057Z",
|
|
"CreateIndex": 7,
|
|
"ModifyIndex": 7
|
|
}
|
|
```
|
|
|
|
### Sample Operator Payload
|
|
|
|
```json
|
|
{
|
|
"BootstrapSecret": "2b778dd9-f5f1-6f29-b4b4-9a5fa948757a"
|
|
}
|
|
```
|
|
|
|
### Sample Request With Operator Token
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data @root-token.json \
|
|
https://localhost:4646/v1/acl/bootstrap
|
|
```
|
|
|
|
### Sample Response With Operator Token
|
|
|
|
```json
|
|
{
|
|
"AccessorID": "b780e702-98ce-521f-2e5f-c6b87de05b24",
|
|
"SecretID": "2b778dd9-f5f1-6f29-b4b4-9a5fa948757a",
|
|
"Name": "Bootstrap Token",
|
|
"Type": "management",
|
|
"Policies": null,
|
|
"Global": true,
|
|
"CreateTime": "2017-08-23T22:47:14.695408057Z",
|
|
"CreateIndex": 7,
|
|
"ModifyIndex": 7
|
|
}
|
|
```
|
|
|
|
## List Tokens
|
|
|
|
This endpoint lists all ACL tokens. This lists the local tokens and the global
|
|
tokens which have been replicated to the region, and may lag behind the authoritative region.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------- | ------------------ |
|
|
| `GET` | `/acl/tokens` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/api-docs#blocking-queries), [consistency modes](/api-docs#consistency-modes) and
|
|
[required ACLs](/api-docs#acls).
|
|
|
|
| Blocking Queries | Consistency Modes | ACL Required |
|
|
| ---------------- | ----------------- | ------------ |
|
|
| `YES` | `all` | `management` |
|
|
|
|
### Parameters
|
|
|
|
- `global` `(bool: false)` - If true, only return ACL tokens that are
|
|
replicated globally to all regions.
|
|
|
|
- `prefix` `(string: "")` - Specifies a string to filter ACL tokens based on an
|
|
accessor ID prefix. Because the value is decoded to bytes, the prefix must
|
|
have an even number of hexadecimal characters (0-9a-f). This is specified as
|
|
a query string parameter.
|
|
|
|
- `next_token` `(string: "")` - This endpoint supports paging. The `next_token`
|
|
parameter accepts a string which identifies the next expected ACL token. This
|
|
value can be obtained from the `X-Nomad-NextToken` header from the previous
|
|
response.
|
|
|
|
- `per_page` `(int: 0)` - Specifies a maximum number of ACL tokens to return
|
|
for this request. If omitted, the response is not paginated. The value of the
|
|
`X-Nomad-NextToken` header of the last response can be used as the
|
|
`next_token` of the next request to fetch additional pages.
|
|
|
|
- `filter` `(string: "")` - Specifies the [expression](/api-docs#filtering)
|
|
used to filter the results. Consider using pagination or a query parameter to
|
|
reduce resource used to serve the request.
|
|
|
|
- `reverse` `(bool: false)` - Specifies the list of returned ACL tokens should
|
|
be sorted in the reverse order. By default ACL tokens are returned sorted in
|
|
chronological order (older ACL tokens first), or in lexicographical order by
|
|
their ID if the `prefix` or `global` query parameters are used.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
https://localhost:4646/v1/acl/tokens
|
|
```
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
https://localhost:4646/v1/acl/tokens?prefix=3da2ed52
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"AccessorID": "b780e702-98ce-521f-2e5f-c6b87de05b24",
|
|
"Name": "Bootstrap Token",
|
|
"Type": "management",
|
|
"Policies": null,
|
|
"Global": true,
|
|
"CreateTime": "2017-08-23T22:47:14.695408057Z",
|
|
"CreateIndex": 7,
|
|
"ModifyIndex": 7
|
|
}
|
|
]
|
|
```
|
|
|
|
## Create Token
|
|
|
|
This endpoint creates an ACL Token. If the token is a global token, the request
|
|
is forwarded to the authoritative region.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------ | ------------------ |
|
|
| `POST` | `/acl/token` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/api-docs#blocking-queries) and
|
|
[required ACLs](/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | ------------ |
|
|
| `NO` | `management` |
|
|
|
|
### Parameters
|
|
|
|
- `Name` `(string: <optional>)` - Specifies the human readable name of the token.
|
|
|
|
- `Type` `(string: <required>)` - Specifies the type of token. Must be either `client` or `management`.
|
|
|
|
- `Policies` `(array<string>: <required>)` - Must be null or blank for `management` type tokens, otherwise must specify at least one policy for `client` type tokens.
|
|
|
|
- `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.
|
|
|
|
### Sample Payload
|
|
|
|
```json
|
|
{
|
|
"Name": "Readonly token",
|
|
"Type": "client",
|
|
"Policies": ["readonly"],
|
|
"Global": false
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data @payload.json \
|
|
https://localhost:4646/v1/acl/token
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"AccessorID": "aa534e09-6a07-0a45-2295-a7f77063d429",
|
|
"SecretID": "8176afd3-772d-0b71-8f85-7fa5d903e9d4",
|
|
"Name": "Readonly token",
|
|
"Type": "client",
|
|
"Policies": ["readonly"],
|
|
"Global": false,
|
|
"CreateTime": "2017-08-23T23:25:41.429154233Z",
|
|
"CreateIndex": 52,
|
|
"ModifyIndex": 52
|
|
}
|
|
```
|
|
|
|
## Update Token
|
|
|
|
This endpoint updates an existing ACL Token. If the token is a global token, the request
|
|
is forwarded to the authoritative region. Note that a token cannot be switched from global
|
|
to local or visa versa.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------------------- | ------------------ |
|
|
| `POST` | `/acl/token/:accessor_id` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/api-docs#blocking-queries) and
|
|
[required ACLs](/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | ------------ |
|
|
| `NO` | `management` |
|
|
|
|
### Parameters
|
|
|
|
- `AccessorID` `(string: <required>)` - Specifies the token (by accessor) that is being updated. Must match payload body and request path.
|
|
|
|
- `Name` `(string: <optional>)` - Specifies the human readable name of the token.
|
|
|
|
- `Type` `(string: <required>)` - Specifies the type of token. Must be either `client` or `management`.
|
|
|
|
- `Policies` `(array<string>: <required>)` - Must be null or blank for `management` type tokens, otherwise must specify at least one policy for `client` type tokens.
|
|
|
|
### Sample Payload
|
|
|
|
```json
|
|
{
|
|
"AccessorID": "aa534e09-6a07-0a45-2295-a7f77063d429",
|
|
"Name": "Read-write token",
|
|
"Type": "client",
|
|
"Policies": ["readwrite"]
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--data @payload.json \
|
|
https://localhost:4646/v1/acl/token/aa534e09-6a07-0a45-2295-a7f77063d429
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"AccessorID": "aa534e09-6a07-0a45-2295-a7f77063d429",
|
|
"SecretID": "8176afd3-772d-0b71-8f85-7fa5d903e9d4",
|
|
"Name": "Read-write token",
|
|
"Type": "client",
|
|
"Policies": ["readwrite"],
|
|
"Global": false,
|
|
"CreateTime": "2017-08-23T23:25:41.429154233Z",
|
|
"CreateIndex": 52,
|
|
"ModifyIndex": 64
|
|
}
|
|
```
|
|
|
|
## Read Token
|
|
|
|
This endpoint reads an ACL token with the given accessor. If the token is a global token
|
|
which has been replicated to the region it may lag behind the authoritative region.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------------------- | ------------------ |
|
|
| `GET` | `/acl/token/:accessor_id` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/api-docs#blocking-queries), [consistency modes](/api-docs#consistency-modes) and
|
|
[required ACLs](/api-docs#acls).
|
|
|
|
| Blocking Queries | Consistency Modes | ACL Required |
|
|
| ---------------- | ----------------- | -------------------------------------------------- |
|
|
| `YES` | `all` | `management` or a SecretID matching the AccessorID |
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
https://localhost:4646/v1/acl/token/aa534e09-6a07-0a45-2295-a7f77063d429
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"AccessorID": "aa534e09-6a07-0a45-2295-a7f77063d429",
|
|
"SecretID": "8176afd3-772d-0b71-8f85-7fa5d903e9d4",
|
|
"Name": "Read-write token",
|
|
"Type": "client",
|
|
"Policies": ["readwrite"],
|
|
"Global": false,
|
|
"CreateTime": "2017-08-23T23:25:41.429154233Z",
|
|
"CreateIndex": 52,
|
|
"ModifyIndex": 64
|
|
}
|
|
```
|
|
|
|
## Read Self Token
|
|
|
|
This endpoint reads the ACL token given by the passed SecretID. If the token is a global token
|
|
which has been replicated to the region it may lag behind the authoritative region.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ----------------- | ------------------ |
|
|
| `GET` | `/acl/token/self` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/api-docs#blocking-queries), [consistency modes](/api-docs#consistency-modes) and
|
|
[required ACLs](/api-docs#acls).
|
|
|
|
| Blocking Queries | Consistency Modes | ACL Required |
|
|
| ---------------- | ----------------- | ------------------- |
|
|
| `YES` | `all` | Any valid ACL token |
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--header "X-Nomad-Token: 8176afd3-772d-0b71-8f85-7fa5d903e9d4" \
|
|
https://localhost:4646/v1/acl/token/self
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"AccessorID": "aa534e09-6a07-0a45-2295-a7f77063d429",
|
|
"SecretID": "8176afd3-772d-0b71-8f85-7fa5d903e9d4",
|
|
"Name": "Read-write token",
|
|
"Type": "client",
|
|
"Policies": ["readwrite"],
|
|
"Global": false,
|
|
"CreateTime": "2017-08-23T23:25:41.429154233Z",
|
|
"CreateIndex": 52,
|
|
"ModifyIndex": 64
|
|
}
|
|
```
|
|
|
|
## Delete Token
|
|
|
|
This endpoint deletes the ACL token by accessor. This request is forwarded to the
|
|
authoritative region for global tokens.
|
|
|
|
| Method | Path | Produces |
|
|
| -------- | ------------------------- | -------------- |
|
|
| `DELETE` | `/acl/token/:accessor_id` | `(empty body)` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/api-docs#blocking-queries) and
|
|
[required ACLs](/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | ------------ |
|
|
| `NO` | `management` |
|
|
|
|
### Parameters
|
|
|
|
- `accessor_id` `(string: <required>)` - Specifies the ACL token accessor ID.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request DELETE \
|
|
https://localhost:4646/v1/acl/token/aa534e09-6a07-0a45-2295-a7f77063d429
|
|
```
|
|
|
|
## Upsert One-Time Token
|
|
|
|
This endpoint creates a one-time token for the ACL token provided in the
|
|
`X-Nomad-Token` header. Returns 403 if the token header is not set.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | -------------------- | ------------------ |
|
|
| `POST` | `/acl/token/onetime` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/api-docs#blocking-queries) and
|
|
[required ACLs](/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | ------------ |
|
|
| `NO` | `any` |
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
-H "X-Nomad-Token: aa534e09-6a07-0a45-2295-a7f77063d429" \
|
|
https://localhost:4646/v1/acl/token/onetime
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Index": 15,
|
|
"OneTimeToken": {
|
|
"AccessorID": "b780e702-98ce-521f-2e5f-c6b87de05b24",
|
|
"CreateIndex": 7,
|
|
"ExpiresAt": "2017-08-23T22:47:14.695408057Z",
|
|
"ModifyIndex": 7,
|
|
"OneTimeSecretID": "3f4a0fcd-7c42-773c-25db-2d31ba0c05fe"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Exchange One-Time Token
|
|
|
|
This endpoint exchanges a one-time token for the original ACL token used to
|
|
create it.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ----------------------------- | ------------------ |
|
|
| `POST` | `/acl/token/onetime/exchange` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for
|
|
[blocking queries](/api-docs#blocking-queries) and
|
|
[required ACLs](/api-docs#acls).
|
|
|
|
| Blocking Queries | ACL Required |
|
|
| ---------------- | ------------ |
|
|
| `NO` | `any` |
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
-d '{ "OneTimeSecretID": "aa534e09-6a07-0a45-2295-a7f77063d429" } \
|
|
https://localhost:4646/v1/acl/token/onetime/exchange
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Index": 17,
|
|
"Token": {
|
|
"AccessorID": "b780e702-98ce-521f-2e5f-c6b87de05b24",
|
|
"CreateIndex": 7,
|
|
"CreateTime": "2017-08-23T22:47:14.695408057Z",
|
|
"Global": true,
|
|
"Hash": "UhZESkSFGFfX7eBgq5Uwph30OctbUbpe8+dlH2i4whA=",
|
|
"ModifyIndex": 7,
|
|
"Name": "Developer token",
|
|
"Policies": ["developer"],
|
|
"SecretID": "3f4a0fcd-7c42-773c-25db-2d31ba0c05fe",
|
|
"Type": "client"
|
|
}
|
|
}
|
|
```
|