• 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. Roles
  • Nomad
  • v1.3.x
  • v1.2.x
  • v1.1.x
  • v1.0.x
  • v0.12.x
  • v0.11.x

ยปACL Roles HTTP API

The /acl/roles and /acl/role/ endpoints are used to manage ACL Roles.

Create Role

This endpoint creates an ACL Role. The request is always forwarded to the authoritative region.

MethodPathProduces
POST/acl/roleapplication/json

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

Blocking QueriesACL Required
NOmanagement

Parameters

  • Name (string: <required>) - Specifies the human-readable name of the ACL Role. The name can contain alphanumeric characters, dashes, and underscores. This name must be unique and must not exceed 128 characters.

  • Description (string: <optional>) - A free form human-readable description of the ACL Role. It must not exceed 256 characters.

  • Policies (array<ACLRolePolicyLink>) The list of policies that should be applied to the role. An ACLRolePolicyLink is an object with a "Name" field to specify a policy.

Sample Payload

{
  "Name": "example-acl-role",
  "Description": "my example ACL Role",
  "Policies": [
    {
      "Name": "example-acl-policy"
    }
  ]
}

Sample Request

$ curl \
    --request POST \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    --data @payload.json \
    https://localhost:4646/v1/acl/role

Sample Response

{
  "CreateIndex": 26,
  "Description": "my example ACL Role",
  "ID": "77c50812-fcdd-701b-9f1a-6cf55387b09d",
  "ModifyIndex": 26,
  "Name": "example-acl-role",
  "Policies": [
    {
      "Name": "example-acl-policy"
    }
  ]
}

Update Token

This endpoint updates an existing ACL Role. The request is always forwarded to the authoritative region.

MethodPathProduces
POST/acl/role/:role_idapplication/json

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

Blocking QueriesACL Required
NOmanagement

Parameters

  • ID (string: <required>) - Specifies the ACL Role, by ID, that is being updated. Must match payload body and request path.

  • Name (string: <required>) - Specifies the human-readable name of the ACL Role. The name can contain alphanumeric characters, dashes, and underscores. This name must be unique a must not exceed 128 characters.

  • Description (string: <optional>) - A free form human-readable description of the ACL Role. It must not exceed 256 characters.

  • Policies (array<ACLRolePolicyLink>) The list of policies that should be applied to the role. An ACLRolePolicyLink is an object with a "Name" field to specify a policy.

Sample Payload

{
  "ID": "77c50812-fcdd-701b-9f1a-6cf55387b09d",
  "Name": "example-acl-role",
  "Description": "my example ACL Role",
  "Policies": [
    {
      "Name": "example-acl-policy"
    }
  ]
}

Sample Request

$ curl \
    --request POST \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    --data @payload.json \
    https://localhost:4646/v1/acl/role/77c50812-fcdd-701b-9f1a-6cf55387b09d

Sample Response

{
  "CreateIndex": 26,
  "Description": "my example ACL Role",
  "ID": "77c50812-fcdd-701b-9f1a-6cf55387b09d",
  "ModifyIndex": 26,
  "Name": "example-acl-role",
  "Policies": [
    {
      "Name": "example-acl-policy"
    }
  ]
}

List Roles

This endpoint lists all ACL Roles. This lists the roles that have been replicated to the region, and may lag behind the authoritative region.

MethodPathProduces
GET/acl/rolesapplication/json

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

Blocking QueriesConsistency ModesACL Required
YESallmanagement for all roles.
Output when given a non-management token will be limited to the roles on the token itself

Parameters

  • prefix (string: "") - Specifies a string to filter ACL Roles based on an ID prefix. This is specified as a query string parameter. Because the value is decoded to bytes, the prefix must have an even number of hexadecimal characters (0-9a-f).

Sample Request

$ curl \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    https://localhost:4646/v1/acl/roles
$ curl \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    https://localhost:4646/v1/acl/roles?prefix=25ba81

Sample Response

[
  {
    "CreateIndex": 26,
    "Description": "my example ACL Role",
    "ID": "77c50812-fcdd-701b-9f1a-6cf55387b09d",
    "ModifyIndex": 26,
    "Name": "example-acl-role",
    "Policies": [
      {
        "Name": "example-acl-policy"
      }
    ]
  }
]

Read Role by ID

This endpoint reads an ACL Role with the given ID. This queries the role that has been replicated to the region, and may lag behind the authoritative region.

MethodPathProduces
GET/acl/role/:role_idapplication/json

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

Blocking QueriesConsistency ModesACL Required
YESallmanagement or token with access to role

Parameters

  • :role_id (string: <required>) - Specifies the ID of the ACL Role. This is specified as part of the path.

Sample Request

$ curl \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    https://localhost:4646/v1/acl/role/77c50812-fcdd-701b-9f1a-6cf55387b09d

Sample Response

{
  "CreateIndex": 26,
  "Description": "my example ACL Role",
  "ID": "77c50812-fcdd-701b-9f1a-6cf55387b09d",
  "ModifyIndex": 26,
  "Name": "example-acl-role",
  "Policies": [
    {
      "Name": "example-acl-policy"
    }
  ]
}

Read Role by Name

This endpoint reads an ACL Role with the given name. This queries the role that has been replicated to the region, and may lag behind the authoritative region.

MethodPathProduces
GET/acl/role/name/:role_nameapplication/json

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

Blocking QueriesConsistency ModesACL Required
YESallmanagement or token with access to role

Parameters

  • :role_name (string: <required>) - Specifies the Name of the ACL Role. This is specified as part of the path.

Sample Request

$ curl \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    https://localhost:4646/v1/acl/role/name/example-acl-role

Sample Response

{
  "CreateIndex": 26,
  "Description": "my example ACL Role",
  "ID": "77c50812-fcdd-701b-9f1a-6cf55387b09d",
  "ModifyIndex": 26,
  "Name": "example-acl-role",
  "Policies": [
    {
      "Name": "example-acl-policy"
    }
  ]
}

Delete Role

This endpoint deletes the ACL role as identified by the ID. This request is always forwarded to the authoritative region.

MethodPathProduces
DELETE/acl/role/:role_id(empty body)

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

Blocking QueriesACL Required
NOmanagement

Parameters

  • role_id (string: <required>) - Specifies the ID of role to delete and is specified as part of the path.

Sample Request

$ curl \
    --request DELETE \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    https://localhost:4646/v1/acl/role/77c50812-fcdd-701b-9f1a-6cf55387b09d
Edit this page on GitHub

On this page

  1. ACL Roles HTTP API
  2. Create Role
  3. Update Token
  4. List Roles
  5. Read Role by ID
  6. Read Role by Name
  7. Delete Role
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)