---
layout: api
page_title: ACL auth methods - HTTP API
description: The /acl/auth-methods endpoints are used to configure and manage ACL auth methods.
---

# ACL auth methods HTTP API

The `/acl/auth-methods` and `/acl/auth-method` endpoints are used to manage ACL auth methods.

## Create auth method

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

| Method | Path                  | Produces           |
| ------ | --------------------- | ------------------ |
| `POST` | `/v1/acl/auth-method` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).

| Blocking Queries | ACL Required |
| ---------------- | ------------ |
| `NO`             | `management` |

### Parameters

@include 'api-docs/auth-method-params.mdx'

### Sample payload

```json
{
  "Name": "example-acl-auth-method",
  "Type": "OIDC",
  "TokenLocality": "local",
  "TokenNameFormat": "${auth_method_type}-${value.user}",
  "MaxTokenTTL": "1h0m0s",
  "Default": false,
  "Config": {
    "OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/",
    "OIDCClientID": "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt",
    "OIDCClientSecret": "example-client-secret",
    "OIDCScopes": [
      "groups"
    ],
    "BoundAudiences": [
      "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt"
    ],
    "AllowedRedirectURIs": [
      "http://localhost:4646/oidc/callback"
    ],
    "ClaimMappings": {
      "http://example.com/first_name": "first_name",
      "http://example.com/last_name": "last_name"
    },
    "ListClaimMappings": {
      "http://nomad.com/groups": "groups"
    }
  }
}
```

### Sample request

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

### Sample response

```json
{
    "MaxTokenTTL": "1h0m0s",
    "Name": "example-acl-auth-method",
    "Type": "OIDC",
    "TokenLocality": "local",
    "TokenNameFormat": "${auth_method_type}-${value.user}",
    "Default": false,
    "Config": {
        "OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/",
        "OIDCClientID": "v1rpi2myptmv1rpi2myptmv1rpi2mypt",
        "OIDCClientSecret": "redacted",
        "OIDCScopes": [
            "groups"
        ],
        "BoundAudiences": [
            "v1rpi2myptmv1rpi2myptmv1rpi2mypt"
        ],
        "AllowedRedirectURIs": [
            "http://localhost:4646/oidc/callback"
        ],
        "DiscoveryCaPem": null,
        "SigningAlgs": null,
        "ClaimMappings": {
            "http://example.com/first_name": "first_name",
            "http://example.com/last_name": "last_name"
        },
        "ListClaimMappings": {
            "http://nomad.com/groups": "groups"
        }
    },
    "CreateTime": "2022-12-08T11:04:43.46206Z",
    "ModifyTime": "2022-12-08T11:04:43.46206Z",
    "CreateIndex": 12,
    "ModifyIndex": 12
}
```

## Update auth method

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

| Method | Path                               | Produces           |
| ------ | ---------------------------------- | ------------------ |
| `POST` | `/v1/acl/auth-method/:method_name` | `application/json` |

The table below shows this endpoint's support for [blocking
queries](/nomad/api-docs#blocking-queries) and [required ACLs](/nomad/api-docs#acls).

| Blocking Queries | ACL Required |
| ---------------- | ------------ |
| `NO`             | `management` |

### Parameters

The parameters are the same as Create.

@include 'api-docs/auth-method-params.mdx'

### Sample Payload

```json
{
  "Name": "example-acl-auth-method",
  "Type": "OIDC",
  "Tokenlocality": "global",
  "TokenNameFormat": "${auth_method_type}-${value.user}",
  "Maxtokenttl": "1h0m0s",
  "Default": true,
  "Config": {
    "OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/",
    "OIDCClientID": "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt",
    "OIDCClientSecret": "example-client-secret",
    "OIDCScopes": [
      "groups"
    ],
    "BoundAudiences": [
      "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt"
    ],
    "AllowedRedirectURIs": [
      "http://localhost:4646/oidc/callback"
    ],
    "ClaimMappings": {
      "http://example.com/first_name": "first_name",
      "http://example.com/last_name": "last_name"
    },
    "ListClaimMappings": {
      "http://nomad.com/groups": "groups"
    }
  }
}
```

### Sample Request

```shell-session
$ curl \
    --request POST \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    --data @payload.json \
    https://localhost:4646/v1/acl/auth-method/example-acl-auth-method
```

### Sample Response

```json
{
    "MaxTokenTTL": "1h0m0s",
    "Name": "example-acl-auth-method",
    "Type": "OIDC",
    "TokenLocality": "global",
    "TokenNameFormat": "${auth_method_type}-${value.user}",
    "Default": true,
    "Config": {
        "OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/",
        "OIDCClientID": "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt",
        "OIDCClientSecret": "redacted",
        "OIDCScopes": [
          "groups"
        ],
        "BoundAudiences": [
          "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt"
        ],
        "AllowedRedirectURIs": [
          "http://localhost:4646/oidc/callback"
        ],
        "ClaimMappings": {
          "http://example.com/first_name": "first_name",
          "http://example.com/last_name": "last_name"
        },
        "ListClaimMappings": {
          "http://nomad.com/groups": "groups"
        }
    },
    "CreateTime": "2022-12-08T11:04:43.46206Z",
    "ModifyTime": "2022-12-08T11:04:43.46206Z",
    "CreateIndex": 12,
    "ModifyIndex": 32
}
```

## List auth methods

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

| Method | Path                   | Produces           |
| ------ | ---------------------- | ------------------ |
| `GET`  | `/v1/acl/auth-methods` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries),
[consistency modes](/nomad/api-docs#consistency-modes) and
[required ACLs](/nomad/api-docs#acls).

| Blocking Queries | Consistency Modes | ACL Required                                                                                                                             |
| ---------------- | ----------------- | ---- |
| `YES`            | `all`             | None |

### Sample request

```shell-session
$ curl \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    https://localhost:4646/v1/acl/auth-methods
```

### Sample response

```json
[
    {
        "CreateIndex": 12,
        "Default": true,
        "ModifyIndex": 32,
        "Name": "example-acl-auth-method",
        "Type": "OIDC"
    }
]
```

## Read auth method by name

This endpoint reads an ACL Auth Method with the given name. This queries the
auth method that has been replicated to the region, and may lag behind the
authoritative region.

| Method | Path                               | Produces           |
| ------ | ---------------------------------- | ------------------ |
| `GET`  | `/v1/acl/auth-method/:method_name` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries),
[consistency modes](/nomad/api-docs#consistency-modes) and
[required ACLs](/nomad/api-docs#acls).

| Blocking Queries | Consistency Modes | ACL Required       |
| ---------------- | ----------------- | ------------------ |
| `YES`            | `all`             | `management` token |

### Parameters

- `:method_name` `(string: <required>)` - Specifies the name of the ACL auth
  method. This is specified as part of the path.

### Sample request

```shell-session
$ curl \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    https://localhost:4646/v1/acl/auth-method/example-acl-auth-method
```

### Sample response

```json
{
    "MaxTokenTTL": "1h0m0s",
    "Name": "example-acl-auth-method",
    "Type": "OIDC",
    "TokenLocality": "global",
    "TokenNameFormat": "${auth_method_type}-${value.user}",
    "Default": true,
    "Config": {
      "OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/",
      "OIDCClientID": "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt",
      "OIDCClientSecret": "example-client-secret",
      "OIDCScopes": [
        "groups"
      ],
      "BoundAudiences": [
        "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt"
      ],
      "AllowedRedirectURIs": [
        "http://localhost:4646/oidc/callback"
      ],
      "ClaimMappings": {
        "http://example.com/first_name": "first_name",
        "http://example.com/last_name": "last_name"
      },
      "ListClaimMappings": {
        "http://nomad.com/groups": "groups"
      }
    },
    "CreateTime": "2022-12-08T11:04:43.46206Z",
    "ModifyTime": "2022-12-08T11:04:43.46206Z",
    "CreateIndex": 12,
    "ModifyIndex": 32
}
```

## Delete auth method

This endpoint deletes the ACL auth method as identified by its name. This
request is always forwarded to the authoritative region.

| Method   | Path                               | Produces       |
| -------- | ---------------------------------- | -------------- |
| `DELETE` | `/v1/acl/auth-method/:method_name` | `(empty body)` |

The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).

| Blocking Queries | ACL Required |
| ---------------- | ------------ |
| `NO`             | `management` |

### Parameters

- `method_name` `(string: <required>)` - Specifies the name of auth method to
  delete and is specified as part of the path.

### Sample Request

```shell-session
$ curl \
    --request DELETE \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    https://localhost:4646/v1/acl/auth-method/example-acl-auth-method
```

[private key jwt]: https://oauth.net/private-key-jwt/
[concepts-assertions]: /nomad/docs/concepts/acl/auth-methods/oidc#client-assertions
[x5t]: https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.7
[x5t#S256]: https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.8
[pkce]: https://oauth.net/2/pkce/
