• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Nomad
  • Install
  • Intro
  • Tutorials
  • Documentation
  • API
  • Tools
  • Plugins
  • Sign up
Nomad Home

API

Skip to main content
  • API

  • Libraries & SDKs
  • JSON Jobs

    • Overview
    • Policies
    • Roles
    • Tokens
  • Agent
  • Allocations
  • Client
  • Deployments
  • Evaluations
  • Events
  • Jobs
  • Namespaces
  • Nodes
  • Metrics
  • Plugins
  • Quotas
  • Recommendations
  • Regions
  • Scaling Policies
  • Search
  • Sentinel Policies
  • Services
  • Status
  • System
  • UI
  • Validate
  • Variables
  • Volumes

  • Resources

  • Tutorial Library
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Nomad
  3. API
  4. ACL
  5. Tokens
  • Nomad
  • v1.3.x
  • v1.2.x
  • v1.1.x
  • v1.0.x
  • v0.12.x
  • v0.11.x

ยป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.

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 is performed.

MethodPathProduces
POST/acl/bootstrapapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
NOnone

Sample Request

$ curl \
    --request POST \
    https://localhost:4646/v1/acl/bootstrap

Sample Response

{
  "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

{
  "BootstrapSecret": "2b778dd9-f5f1-6f29-b4b4-9a5fa948757a"
}

Sample Request With Operator Token

$ curl \
    --request POST \
    --data @root-token.json \
    https://localhost:4646/v1/acl/bootstrap

Sample Response With Operator Token

{
  "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.

MethodPathProduces
GET/acl/tokensapplication/json

The table below shows this endpoint's support for blocking queries, consistency modes and required ACLs.

Blocking QueriesConsistency ModesACL Required
YESallmanagement

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 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

$ curl \
    https://localhost:4646/v1/acl/tokens
$ curl \
    --request POST \
    https://localhost:4646/v1/acl/tokens?prefix=3da2ed52

Sample Response

[
  {
    "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.

MethodPathProduces
POST/acl/tokenapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
NOmanagement

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.

  • 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.

  • ExpirationTTL (duration: 0s) - This is a convenience field and if set will initialize the ExpirationTime field to a value of CreateTime + ExpirationTTL.

Sample Payload

{
  "Name": "Readonly token",
  "Type": "client",
  "Policies": ["readonly"],
  "Global": false
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/acl/token

Sample Response

{
  "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.

MethodPathProduces
POST/acl/token/:accessor_idapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
NOmanagement

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

{
  "AccessorID": "aa534e09-6a07-0a45-2295-a7f77063d429",
  "Name": "Read-write token",
  "Type": "client",
  "Policies": ["readwrite"]
}

Sample Request

$ curl \
    --request POST \
    --data @payload.json \
    https://localhost:4646/v1/acl/token/aa534e09-6a07-0a45-2295-a7f77063d429

Sample Response

{
  "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.

MethodPathProduces
GET/acl/token/:accessor_idapplication/json

The table below shows this endpoint's support for blocking queries, consistency modes and required ACLs.

Blocking QueriesConsistency ModesACL Required
YESallmanagement or a SecretID matching the AccessorID

Sample Request

$ curl \
    https://localhost:4646/v1/acl/token/aa534e09-6a07-0a45-2295-a7f77063d429

Sample Response

{
  "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.

MethodPathProduces
GET/acl/token/selfapplication/json

The table below shows this endpoint's support for blocking queries, consistency modes and required ACLs.

Blocking QueriesConsistency ModesACL Required
YESallAny valid ACL token

Sample Request

$ curl \
    --header "X-Nomad-Token: 8176afd3-772d-0b71-8f85-7fa5d903e9d4" \
    https://localhost:4646/v1/acl/token/self

Sample Response

{
  "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.

MethodPathProduces
DELETE/acl/token/:accessor_id(empty body)

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
NOmanagement

Parameters

  • accessor_id (string: <required>) - Specifies the ACL token accessor ID.

Sample Request

$ 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.

MethodPathProduces
POST/acl/token/onetimeapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
NOany

Sample Request

$ curl \
    --request POST \
    -H "X-Nomad-Token: aa534e09-6a07-0a45-2295-a7f77063d429" \
    https://localhost:4646/v1/acl/token/onetime

Sample Response

{
  "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.

MethodPathProduces
POST/acl/token/onetime/exchangeapplication/json

The table below shows this endpoint's support for blocking queries and required ACLs.

Blocking QueriesACL Required
NOany

Sample Request

$ curl \
    --request POST \
    -d '{ "OneTimeSecretID": "aa534e09-6a07-0a45-2295-a7f77063d429" } \
    https://localhost:4646/v1/acl/token/onetime/exchange

Sample Response

{
  "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"
  }
}
Edit this page on GitHub

On this page

  1. ACL Tokens HTTP API
  2. Bootstrap Token
  3. List Tokens
  4. Create Token
  5. Update Token
  6. Read Token
  7. Read Self Token
  8. Delete Token
  9. Upsert One-Time Token
  10. Exchange One-Time Token
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)