775 lines
26 KiB
Plaintext
775 lines
26 KiB
Plaintext
---
|
|
layout: api
|
|
page_title: ACL Tokens - HTTP API
|
|
description: The /acl/token endpoints manage Consul's ACL Tokens.
|
|
---
|
|
|
|
# ACL Token HTTP API
|
|
|
|
-> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api-docs/acl/legacy).
|
|
|
|
The `/acl/token` endpoints [create](#create-a-token), [read](#read-a-token),
|
|
[update](#update-a-token), [list](#list-tokens), [clone](#clone-a-token) and [delete](#delete-a-token) ACL tokens in Consul.
|
|
|
|
For more information on how to setup ACLs, please check
|
|
the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production).
|
|
|
|
## Create a Token
|
|
|
|
This endpoint creates a new ACL token.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------ | ------------------ |
|
|
| `PUT` | `/acl/token` | `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-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ------------ |
|
|
| `NO` | `none` | `none` | `acl:write` |
|
|
|
|
The corresponding CLI command is [`consul acl token create`](/commands/acl/token/create).
|
|
|
|
### Query Parameters
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the token you create.
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
### JSON Request Body Schema
|
|
|
|
- `AccessorID` `(string: "")` - Specifies a UUID to use as the token's Accessor ID.
|
|
If not specified a UUID will be generated for this field. Added in v1.5.0.
|
|
|
|
- `SecretID` `(string: "")` - Specifies a UUID to use as the token's Secret ID.
|
|
If not specified a UUID will be generated for this field. Added in v1.5.0.
|
|
**Note**: The SecretID is used to authorize operations against Consul and should
|
|
be generated from an appropriate cryptographic source.
|
|
|
|
- `Description` `(string: "")` - Free form human readable description of the token.
|
|
|
|
- `Policies` `(array<PolicyLink>)` - The list of policies that should be
|
|
applied to the token. A PolicyLink is an object with an "ID" and/or "Name"
|
|
field to specify a policy. With the PolicyLink, tokens can be linked to
|
|
policies either by the policy name or by the policy ID. When policies are
|
|
linked by name they will be internally resolved to the policy ID. With
|
|
linking tokens internally by IDs, Consul enables policy renaming without
|
|
breaking tokens.
|
|
|
|
- `Roles` `(array<RoleLink>)` - The list of roles that should be applied to the
|
|
token. A RoleLink is an object with an "ID" and/or "Name" field to specify a
|
|
role. With the RoleLink, tokens can be linked to roles either by the role
|
|
name or by the role ID. When roles are linked by name they will be internally
|
|
resolved to the role ID. With linking tokens internally by IDs, Consul
|
|
enables role renaming without breaking tokens. Added in Consul 1.5.0.
|
|
|
|
- `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service
|
|
identities](/docs/security/acl#service-identities) that should be
|
|
applied to the token. Added in Consul 1.5.0.
|
|
|
|
- `ServiceName` `(string: <required>)` - The name of the service. The name
|
|
must be no longer than 256 characters, must start and end with a lowercase
|
|
alphanumeric character, and can only contain lowercase alphanumeric
|
|
characters as well as `-` and `_`.
|
|
|
|
- `Datacenters` `(array<string>)` - Specifies the datacenters the effective
|
|
policy is valid within. When no datacenters are provided the effective
|
|
policy is valid in all datacenters including those which do not yet exist
|
|
but may in the future.
|
|
|
|
- `NodeIdentities` `(array<NodeIdentity>)` - The list of [node
|
|
identities](/docs/security/acl#node-identities) that should be
|
|
applied to the token. Added in Consul 1.8.1.
|
|
|
|
- `NodeName` `(string: <required>)` - The name of the node. The name
|
|
must be no longer than 256 characters, must start and end with a lowercase
|
|
alphanumeric character, and can only contain lowercase alphanumeric
|
|
characters as well as `-` and `_`.
|
|
|
|
- `Datacenter` `(string: <required>)` - Specifies the nodes datacenter. This
|
|
will result in effective policy only being valid in that datacenter.
|
|
|
|
- `Local` `(bool: false)` - If true, indicates that the token should not be
|
|
replicated globally and instead be local to the current datacenter.
|
|
|
|
- `ExpirationTime` `(time: "")`- If set this represents the point after which a
|
|
token should be considered revoked and is eligible for destruction. The
|
|
default unset value represents NO expiration. This value must be between 1
|
|
minute and 24 hours in the future. Added in Consul 1.5.0.
|
|
|
|
- `ExpirationTTL` `(duration: 0s)` - This is a convenience field and if set
|
|
will initialize the `ExpirationTime` field to a value of `CreateTime + ExpirationTTL`. This field is not persisted beyond its initial use. Can be
|
|
specified in the form of `"60s"` or `"5m"` (i.e., 60 seconds or 5 minutes,
|
|
respectively). This value must be no smaller than 1 minute and no longer than
|
|
24 hours. Added in Consul 1.5.0.
|
|
|
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the token you create.
|
|
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
|
|
{
|
|
"Description": "Agent token for 'node1'",
|
|
"Policies": [
|
|
{
|
|
"ID": "165d4317-e379-f732-ce70-86278c4558f7"
|
|
},
|
|
{
|
|
"Name": "node-read"
|
|
}
|
|
],
|
|
"Local": false
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl --request PUT \
|
|
--data @payload.json \
|
|
http://127.0.0.1:8500/v1/acl/token
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"AccessorID": "6a1253d2-1785-24fd-91c2-f8e78c745511",
|
|
"SecretID": "45a3bd52-07c7-47a4-52fd-0745e0cfe967",
|
|
"Description": "Agent token for 'node1'",
|
|
"Policies": [
|
|
{
|
|
"ID": "165d4317-e379-f732-ce70-86278c4558f7",
|
|
"Name": "node1-write"
|
|
},
|
|
{
|
|
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
|
"Name": "node-read"
|
|
}
|
|
],
|
|
"Local": false,
|
|
"CreateTime": "2018-10-24T12:25:06.921933-04:00",
|
|
"Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
|
|
"CreateIndex": 59,
|
|
"ModifyIndex": 59
|
|
}
|
|
```
|
|
|
|
## Read a Token
|
|
|
|
This endpoint reads an ACL token with the given Accessor ID.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------------------ | ------------------ |
|
|
| `GET` | `/acl/token/:AccessorID` | `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-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ------------ |
|
|
| `YES` | `all` | `none` | `acl:read` |
|
|
|
|
The corresponding CLI command is [`consul acl token read`](/commands/acl/token/read).
|
|
|
|
### Path Parameters
|
|
|
|
- `AccessorID` `(string: <required>)` - Specifies the accessor ID of the token you lookup.
|
|
|
|
### Query Parameters
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the token you lookup.
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
- `expanded` `(bool: false)` - If this field is set, the contents of all policies and
|
|
roles affecting the token will also be returned.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl --request GET http://127.0.0.1:8500/v1/acl/token/6a1253d2-1785-24fd-91c2-f8e78c745511
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
-> **Note** If the token used for accessing the API has `acl:write` permissions,
|
|
then the `SecretID` will contain the tokens real value. Only when accessed with
|
|
a token with only `acl:read` permissions will the `SecretID` be redacted. This
|
|
is to prevent privilege escalation whereby having `acl:read` privileges allows
|
|
for reading other secrets which given even more permissions.
|
|
|
|
```json
|
|
{
|
|
"AccessorID": "6a1253d2-1785-24fd-91c2-f8e78c745511",
|
|
"SecretID": "<hidden>",
|
|
"Description": "Agent token for 'node1'",
|
|
"Policies": [
|
|
{
|
|
"ID": "165d4317-e379-f732-ce70-86278c4558f7",
|
|
"Name": "node1-write"
|
|
},
|
|
{
|
|
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
|
"Name": "node-read"
|
|
}
|
|
],
|
|
"Local": false,
|
|
"CreateTime": "2018-10-24T12:25:06.921933-04:00",
|
|
"Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
|
|
"CreateIndex": 59,
|
|
"ModifyIndex": 59
|
|
}
|
|
```
|
|
|
|
Sample response when setting the `expanded` parameter:
|
|
|
|
```json
|
|
{
|
|
"AccessorID": "fbd2447f-7479-4329-ad13-b021d74f86ba",
|
|
"SecretID": "869c6e91-4de9-4dab-b56e-87548435f9c6",
|
|
"Description": "test token",
|
|
"Policies": [
|
|
{
|
|
"ID": "beb04680-815b-4d7c-9e33-3d707c24672c",
|
|
"Name": "foo"
|
|
},
|
|
{
|
|
"ID": "18788457-584c-4812-80d3-23d403148a90",
|
|
"Name": "bar"
|
|
}
|
|
],
|
|
"Local": false,
|
|
"CreateTime": "2020-05-22T18:52:31Z",
|
|
"Hash": "YWJjZGVmZ2g=",
|
|
"ExpandedPolicies": [
|
|
{
|
|
"ID": "beb04680-815b-4d7c-9e33-3d707c24672c",
|
|
"Name": "foo",
|
|
"Description": "user policy on token",
|
|
"Rules": "service_prefix \"\" {\n policy = \"read\"\n}",
|
|
"Datacenters": null,
|
|
"Hash": null,
|
|
"CreateIndex": 0,
|
|
"ModifyIndex": 0
|
|
},
|
|
{
|
|
"ID": "18788457-584c-4812-80d3-23d403148a90",
|
|
"Name": "bar",
|
|
"Description": "other user policy on token",
|
|
"Rules": "operator = \"read\"",
|
|
"Datacenters": null,
|
|
"Hash": null,
|
|
"CreateIndex": 0,
|
|
"ModifyIndex": 0
|
|
},
|
|
{
|
|
"ID": "6204f4cd-4709-441c-ac1b-cb029e940263",
|
|
"Name": "admin policy",
|
|
"Description": "policy for admin role",
|
|
"Rules": "operator = \"write\"",
|
|
"Datacenters": null,
|
|
"Hash": null,
|
|
"CreateIndex": 0,
|
|
"ModifyIndex": 0
|
|
}
|
|
],
|
|
"ExpandedRoles": [
|
|
{
|
|
"ID": "3b0a78fe-b9c3-40de-b8ea-7d4d6674b366",
|
|
"Name": "admin",
|
|
"Description": "admin role",
|
|
"Policies": [
|
|
{
|
|
"ID": "6204f4cd-4709-441c-ac1b-cb029e940263",
|
|
"Name": "admin policy"
|
|
}
|
|
],
|
|
"ServiceIdentities": [
|
|
{
|
|
"ServiceName": "web",
|
|
"Datacenters": [
|
|
"southwest"
|
|
]
|
|
}
|
|
],
|
|
"Hash": null,
|
|
"CreateIndex": 0,
|
|
"ModifyIndex": 0
|
|
}
|
|
],
|
|
"NamespaceDefaultPolicies": null,
|
|
"NamespaceDefaultRoles": null,
|
|
"AgentACLDefaultPolicy": "allow",
|
|
"AgentACLDownPolicy": "deny",
|
|
"ResolvedByAgent": "server-1",
|
|
"CreateIndex": 42,
|
|
"ModifyIndex": 100
|
|
}
|
|
```
|
|
|
|
## Read Self Token
|
|
|
|
This endpoint returns the ACL token details that matches the secret ID
|
|
specified with the `X-Consul-Token` header or the `token` query parameter.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ----------------- | ------------------ |
|
|
| `GET` | `/acl/token/self` | `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-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ------------ |
|
|
| `YES` | `all` | `none` | `none` |
|
|
|
|
-> **Note** - This endpoint requires no specific privileges as it is just
|
|
retrieving the data for a token that you must already possess its secret.
|
|
|
|
The corresponding CLI command is [`consul acl token read -self`](/commands/acl/token/read#self).
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl --header "X-Consul-Token: 6a1253d2-1785-24fd-91c2-f8e78c745511" \
|
|
http://127.0.0.1:8500/v1/acl/token/self
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"AccessorID": "6a1253d2-1785-24fd-91c2-f8e78c745511",
|
|
"SecretID": "45a3bd52-07c7-47a4-52fd-0745e0cfe967",
|
|
"Description": "Agent token for 'node1'",
|
|
"Policies": [
|
|
{
|
|
"ID": "165d4317-e379-f732-ce70-86278c4558f7",
|
|
"Name": "node1-write"
|
|
},
|
|
{
|
|
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
|
"Name": "node-read"
|
|
}
|
|
],
|
|
"Local": false,
|
|
"CreateTime": "2018-10-24T12:25:06.921933-04:00",
|
|
"Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
|
|
"CreateIndex": 59,
|
|
"ModifyIndex": 59
|
|
}
|
|
```
|
|
|
|
## Update a Token
|
|
|
|
This endpoint updates an existing ACL token.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------------------ | ------------------ |
|
|
| `PUT` | `/acl/token/:AccessorID` | `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-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ------------ |
|
|
| `NO` | `none` | `none` | `acl:write` |
|
|
|
|
The corresponding CLI command is [`consul acl token update`](/commands/acl/token/update).
|
|
|
|
### Path Parameters
|
|
|
|
- `AccessorID` `(string: <required>)` - Specifies the accessor ID of the token you update.
|
|
|
|
### Query Parameters
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the token you update.
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
### JSON Request Body Schema
|
|
|
|
- `AccessorID` `(string: "")` - Specifies the accessor ID of the token being updated.
|
|
This field is required in the URL path but may also be specified in the JSON body.
|
|
If specified in both places then they must be an exact match.
|
|
This field is immutable. If not present in
|
|
the body and only in the URL then it will be filled in by Consul.
|
|
|
|
- `SecretID` `(string: "")` - Specifies the secret ID of the token being updated. This field is
|
|
immutable so if present in the body then it must match the existing value. If not present
|
|
then the value will be filled in by Consul.
|
|
|
|
- `Description` `(string: "")` - Free form human readable description of this token.
|
|
|
|
- `Policies` `(array<PolicyLink>)` - This is the list of policies that should
|
|
be applied to this token. A PolicyLink is an object with an "ID" and/or
|
|
"Name" field to specify a policy. With the PolicyLink tokens can be linked to policies
|
|
either by the policy name or by the policy ID. When policies are linked by
|
|
name they will internally be resolved to the policy ID. With linking tokens
|
|
internally by IDs, Consul enables policy renaming without breaking tokens.
|
|
|
|
- `Roles` `(array<RoleLink>)` - The list of roles that should be applied to the
|
|
token. A RoleLink is an object with an "ID" and/or "Name" field to specify a
|
|
role. With the RoleLink, tokens can be linked to roles either by the role
|
|
name or by the role ID. When roles are linked by name they will be internally
|
|
resolved to the role ID. With linking tokens internally by IDs, Consul
|
|
enables role renaming without breaking tokens.
|
|
|
|
- `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service
|
|
identities](/docs/security/acl#service-identities) that should be
|
|
applied to the token. Added in Consul 1.5.0.
|
|
|
|
- `ServiceName` `(string: <required>)` - The name of the service. The name
|
|
must be no longer than 256 characters, must start and end with a lowercase
|
|
alphanumeric character, and can only contain lowercase alphanumeric
|
|
characters as well as `-` and `_`.
|
|
|
|
- `Datacenters` `(array<string>)` - Specifies the datacenters the effective
|
|
policy is valid within. When no datacenters are provided the effective
|
|
policy is valid in all datacenters including those which do not yet exist
|
|
but may in the future.
|
|
|
|
- `NodeIdentities` `(array<NodeIdentity>)` - The list of [node
|
|
identities](/docs/security/acl#node-identities) that should be
|
|
applied to the token. Added in Consul 1.8.1.
|
|
|
|
- `NodeName` `(string: <required>)` - The name of the node. The name
|
|
must be no longer than 256 characters, must start and end with a lowercase
|
|
alphanumeric character, and can only contain lowercase alphanumeric
|
|
characters as well as `-` and `_`.
|
|
|
|
- `Datacenter` `(string: <required>)` - Specifies the nodes datacenter. This
|
|
will result in effective policy only being valid in that datacenter.
|
|
|
|
- `Local` `(bool: false)` - If true, indicates that this token should not be
|
|
replicated globally and instead be local to the current datacenter. This
|
|
value must match the existing value or the request will return an error.
|
|
|
|
- `AuthMethod` `(string: "")` - Specifies the name of the auth method that
|
|
created this token. This field is immutable so if present in the body then it
|
|
must match the existing value. If not present then the value will be filled
|
|
in by Consul.
|
|
|
|
- `ExpirationTime` `(time: "")` - Specifies the expiration time for the token
|
|
being updated. This field is immutable so if present in the body then it must
|
|
match the existing value. If not present then the value will be filled in by
|
|
Consul.
|
|
|
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the token you update.
|
|
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
|
|
{
|
|
"Description": "Agent token for 'node1'",
|
|
"Policies": [
|
|
{
|
|
"ID": "165d4317-e379-f732-ce70-86278c4558f7"
|
|
},
|
|
{
|
|
"Name": "node-read"
|
|
},
|
|
{
|
|
"Name": "service-read"
|
|
}
|
|
],
|
|
"Local": false
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl --request PUT \
|
|
--data @payload.json \
|
|
http://127.0.0.1:8500/v1/acl/token/6a1253d2-1785-24fd-91c2-f8e78c745511
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"AccessorID": "6a1253d2-1785-24fd-91c2-f8e78c745511",
|
|
"SecretID": "45a3bd52-07c7-47a4-52fd-0745e0cfe967",
|
|
"Description": "Agent token for 'node1'",
|
|
"Policies": [
|
|
{
|
|
"ID": "165d4317-e379-f732-ce70-86278c4558f7",
|
|
"Name": "node1-write"
|
|
},
|
|
{
|
|
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
|
"Name": "node-read"
|
|
},
|
|
{
|
|
"ID": "93d2226b-2046-4db1-993b-c0581b5d2391",
|
|
"Name": "service-read"
|
|
}
|
|
],
|
|
"Local": false,
|
|
"CreateTime": "2018-10-24T12:25:06.921933-04:00",
|
|
"Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
|
|
"CreateIndex": 59,
|
|
"ModifyIndex": 100
|
|
}
|
|
```
|
|
|
|
## Clone a Token
|
|
|
|
This endpoint clones an existing ACL token.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------------------------ | ------------------ |
|
|
| `PUT` | `/acl/token/:AccessorID/clone` | `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-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ------------ |
|
|
| `NO` | `none` | `none` | `acl:write` |
|
|
|
|
The corresponding CLI command is [`consul acl token clone`](/commands/acl/token/clone).
|
|
|
|
### Path Parameters
|
|
|
|
- `AccessorID` `(string: <required>)` - The accessor ID of the token to clone.
|
|
|
|
### Query Parameters
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the token you clone.
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
### JSON Request Body Schema
|
|
|
|
- `Description` `(string: "")` - Free form human readable description for the cloned token.
|
|
|
|
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the token you clone.
|
|
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
|
|
{
|
|
"Description": "Clone of Agent token for 'node1'"
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl --request PUT \
|
|
--data @payload.json \
|
|
http://127.0.0.1:8500/v1/acl/token/6a1253d2-1785-24fd-91c2-f8e78c745511/clone
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"AccessorID": "773efe2a-1f6f-451f-878c-71be10712bae",
|
|
"SecretID": "8b1247ef-d172-4f99-b050-4dbe5d3df0cb",
|
|
"Description": "Clone of Agent token for 'node1'",
|
|
"Policies": [
|
|
{
|
|
"ID": "165d4317-e379-f732-ce70-86278c4558f7",
|
|
"Name": "node1-write"
|
|
},
|
|
{
|
|
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
|
"Name": "node-read"
|
|
},
|
|
{
|
|
"ID": "93d2226b-2046-4db1-993b-c0581b5d2391",
|
|
"Name": "service-read"
|
|
}
|
|
],
|
|
"Local": false,
|
|
"CreateTime": "2018-10-24T12:25:06.921933-04:00",
|
|
"Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
|
|
"CreateIndex": 128,
|
|
"ModifyIndex": 128
|
|
}
|
|
```
|
|
|
|
## Delete a Token
|
|
|
|
This endpoint deletes an ACL token.
|
|
|
|
| Method | Path | Produces |
|
|
| -------- | ------------------------ | ------------------ |
|
|
| `DELETE` | `/acl/token/:AccessorID` | `application/json` |
|
|
|
|
Even though the return type is application/json, the value is either true or
|
|
false, indicating whether the delete succeeded.
|
|
|
|
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-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ------------ |
|
|
| `NO` | `none` | `none` | `acl:write` |
|
|
|
|
The corresponding CLI command is [`consul acl token delete`](/commands/acl/token/delete).
|
|
|
|
### Path Parameters
|
|
|
|
- `AccessorID` `(string: <required>)` - Specifies the accessor ID of the ACL token to delete.
|
|
|
|
### Query Parameters
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the token you delete.
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl --request DELETE \
|
|
http://127.0.0.1:8500/v1/acl/token/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
true
|
|
```
|
|
|
|
## List Tokens
|
|
|
|
This endpoint lists all the ACL tokens.
|
|
|
|
| Method | Path | Produces |
|
|
| ------ | ------------- | ------------------ |
|
|
| `GET` | `/acl/tokens` | `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-docs/api-structure#authentication).
|
|
|
|
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
|
|
| ---------------- | ----------------- | ------------- | ------------ |
|
|
| `YES` | `all` | `none` | `acl:read` |
|
|
|
|
The corresponding CLI command is [`consul acl token list`](/commands/acl/token/list).
|
|
|
|
### Query Parameters
|
|
|
|
- `policy` `(string: "")` - Filters the token list to those tokens that are
|
|
linked with this specific policy ID.
|
|
|
|
- `role` `(string: "")` - Filters the token list to those tokens that are
|
|
linked with this specific role ID.
|
|
|
|
- `authmethod` `(string: "")` - Filters the token list to those tokens that are
|
|
linked with this specific named auth method.
|
|
|
|
- `authmethod-ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the
|
|
`authmethod` used for token lookup. If not provided, the namespace
|
|
provided by the `ns` parameter or [through other methods](#methods-to-specify-namespace) will be used.
|
|
|
|
- `ns` `(string: "")` <EnterpriseAlert inline /> - Return only the tokens in the specified namespace.
|
|
The namespace may be specified as '\*' to return results for all namespaces.
|
|
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl --request GET http://127.0.0.1:8500/v1/acl/tokens
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
-> **Note** If the token used for accessing the API has `acl:write` permissions,
|
|
then the `SecretID` will contain the tokens real value. Only when accessed with
|
|
a token with only `acl:read` permissions will the `SecretID` be redacted. This
|
|
is to prevent privilege escalation whereby having `acl:read` privileges allows
|
|
for reading other secrets which given even more permissions.
|
|
|
|
```json
|
|
[
|
|
{
|
|
"AccessorID": "6a1253d2-1785-24fd-91c2-f8e78c745511",
|
|
"SecretID": "<hidden>",
|
|
"Description": "Agent token for 'my-agent'",
|
|
"Policies": [
|
|
{
|
|
"ID": "165d4317-e379-f732-ce70-86278c4558f7",
|
|
"Name": "node1-write"
|
|
},
|
|
{
|
|
"ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
|
|
"Name": "node-read"
|
|
}
|
|
],
|
|
"Local": false,
|
|
"CreateTime": "2018-10-24T12:25:06.921933-04:00",
|
|
"Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
|
|
"CreateIndex": 59,
|
|
"ModifyIndex": 59
|
|
},
|
|
{
|
|
"AccessorID": "00000000-0000-0000-0000-000000000002",
|
|
"SecretID": "<hidden>",
|
|
"Description": "Anonymous Token",
|
|
"Policies": null,
|
|
"Local": false,
|
|
"CreateTime": "0001-01-01T00:00:00Z",
|
|
"Hash": "RNVFSWnfd5DUOuB8vplp+imivlIna3fKQVnkUHh21cA=",
|
|
"CreateIndex": 5,
|
|
"ModifyIndex": 5
|
|
},
|
|
{
|
|
"AccessorID": "3328f9a6-433c-02d0-6649-7d07268dfec7",
|
|
"SecretID": "<hidden>",
|
|
"Description": "Bootstrap Token (Global Management)",
|
|
"Policies": [
|
|
{
|
|
"ID": "00000000-0000-0000-0000-000000000001",
|
|
"Name": "global-management"
|
|
}
|
|
],
|
|
"Local": false,
|
|
"CreateTime": "2018-10-24T11:42:02.6427-04:00",
|
|
"Hash": "oyrov6+GFLjo/KZAfqgxF/X4J/3LX0435DOBy9V22I0=",
|
|
"CreateIndex": 12,
|
|
"ModifyIndex": 12
|
|
}
|
|
]
|
|
```
|
|
|
|
## Methods to Specify Namespace <EnterpriseAlert inline />
|
|
|
|
ACL token endpoints
|
|
support several methods for specifying the namespace of the ACL token resources
|
|
with the following order of precedence:
|
|
1. `Namespace` field of the JSON request body -
|
|
only applies to [create](#create-a-token) and [update](#update-a-token) endpoints
|
|
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
|