1---
2layout: api
3page_title: ACL Auth Methods - HTTP API
4sidebar_current: api-acl-auth-methods
5description: |-
6  The /acl/auth-method endpoints manage Consul's ACL Auth Methods.
7---
8
9-> **1.5.0+:**  The auth method APIs are available in Consul versions 1.5.0 and newer.
10
11# ACL Auth Method HTTP API
12
13The `/acl/auth-method` endpoints [create](#create-an-auth-method),
14[read](#read-an-auth-method), [update](#update-an-auth-method),
15[list](#list-auth-methods) and [delete](#delete-an-auth-method)
16ACL auth methods in Consul.
17
18For more information on how to setup ACLs, please see
19the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/production-acls).
20
21## Create an Auth Method
22
23This endpoint creates a new ACL auth method.
24
25| Method | Path                         | Produces                   |
26| ------ | ---------------------------- | -------------------------- |
27| `PUT`  | `/acl/auth-method`           | `application/json`         |
28
29The table below shows this endpoint's support for
30[blocking queries](/api/features/blocking.html),
31[consistency modes](/api/features/consistency.html),
32[agent caching](/api/features/caching.html), and
33[required ACLs](/api/index.html#authentication).
34
35| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
36| ---------------- | ----------------- | ------------- | ------------ |
37| `NO`             | `none`            | `none`        | `acl:write`  |
38
39### Payload Fields
40
41- `Name` `(string: <required>)` - Specifies a name for the ACL auth method. The
42  name can contain alphanumeric characters, dashes `-`, and  underscores `_`.
43  This field is immutable and must be unique.
44
45- `Type` `(string: <required>)` - The type of auth method being configured.
46  The only allowed value in Consul 1.5.0 is `"kubernetes"`. This field is
47  immutable.
48
49- `Description` `(string: "")` - Free form human readable description of the
50  auth method.
51
52- `Config` `(map[string]string: <required>)` - The raw configuration to use for
53  the chosen auth method. Contents will vary depending upon the type chosen.
54  For more information on configuring specific auth method types, see the [auth
55  method documentation](/docs/acl/acl-auth-methods.html).
56
57- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace to
58  create the auth method within. If not provided in the JSON body, the value of
59  the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
60  If not provided at all, the namespace will be inherited from the request's ACL
61  token or will default to the `default` namespace. Added in Consul 1.7.0.
62
63### Sample Payload
64
65```json
66{
67    "Name": "minikube",
68    "Type": "kubernetes",
69    "Description": "dev minikube cluster",
70    "Config": {
71        "Host": "https://192.0.2.42:8443",
72        "CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
73        "ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
74    }
75}
76```
77
78### Sample Request
79
80```sh
81$ curl -X PUT \
82    --data @payload.json \
83    http://127.0.0.1:8500/v1/acl/auth-method
84```
85
86### Sample Response
87
88```json
89{
90    "Name": "minikube",
91    "Type": "kubernetes",
92    "Description": "dev minikube cluster",
93    "Config": {
94        "Host": "https://192.0.2.42:8443",
95        "CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
96        "ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
97    },
98    "CreateIndex": 15,
99    "ModifyIndex": 15
100}
101```
102
103## Read an Auth Method
104
105This endpoint reads an ACL auth method with the given name. If no
106auth method exists with the given name, a 404 is returned instead of a
107200 response.
108
109| Method | Path                         | Produces                   |
110| ------ | ---------------------------- | -------------------------- |
111| `GET`  | `/acl/auth-method/:name`     | `application/json`         |
112
113The table below shows this endpoint's support for
114[blocking queries](/api/features/blocking.html),
115[consistency modes](/api/features/consistency.html),
116[agent caching](/api/features/caching.html), and
117[required ACLs](/api/index.html#authentication).
118
119| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
120| ---------------- | ----------------- | ------------- | ------------ |
121| `YES`            | `all`             | `none`        | `acl:read`   |
122
123### Parameters
124
125- `name` `(string: <required>)` - Specifies the name of the ACL auth method to
126  read. This is required and is specified as part of the URL path.
127
128- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to lookup
129  the auth method within. This value can be specified as the `ns` URL query
130  parameter or in the `X-Consul-Namespace` header. If not provided by either,
131  the namespace will be inherited from the request's ACL token or will default
132  to the `default` namespace. Added in Consul 1.7.0.
133
134### Sample Request
135
136```sh
137$ curl -X GET http://127.0.0.1:8500/v1/acl/auth-method/minikube
138```
139
140### Sample Response
141
142```json
143{
144    "Name": "minikube",
145    "Type": "kubernetes",
146    "Description": "dev minikube cluster",
147    "Config": {
148        "Host": "https://192.0.2.42:8443",
149        "CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
150        "ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
151    },
152    "CreateIndex": 15,
153    "ModifyIndex": 224
154}
155```
156
157## Update an Auth Method
158
159This endpoint updates an existing ACL auth method.
160
161| Method | Path                         | Produces                   |
162| ------ | ---------------------------- | -------------------------- |
163| `PUT`  | `/acl/auth-method/:name`     | `application/json`         |
164
165The table below shows this endpoint's support for
166[blocking queries](/api/features/blocking.html),
167[consistency modes](/api/features/consistency.html),
168[agent caching](/api/features/caching.html), and
169[required ACLs](/api/index.html#authentication).
170
171| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
172| ---------------- | ----------------- | ------------- | ------------ |
173| `NO`             | `none`            | `none`        | `acl:write`  |
174
175### Parameters
176
177- `Name` `(string: <required>)` - Specifies the name of the auth method to
178  update. This is required in the URL path but may also be specified in the
179  JSON body. If specified in both places then they must match exactly.
180
181- `Type` `(string: <required>)` - Specifies the type of the auth method being
182  updated.  This field is immutable so if present in the body then it must
183  match the existing value. If not present then the value will be filled in by
184  Consul.
185
186- `Description` `(string: "")` - Free form human readable description of the
187  auth method.
188
189- `Config` `(map[string]string: <required>)` - The raw configuration to use for
190  the chosen auth method. Contents will vary depending upon the type chosen.
191  For more information on configuring specific auth method types, see the [auth
192  method documentation](/docs/acl/acl-auth-methods.html).
193
194- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of
195  the auth method to update. If not provided in the JSON body, the value of
196  the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
197  If not provided at all, the namespace will be inherited from the request's ACL
198  token or will default to the `default` namespace. Added in Consul 1.7.0.
199
200### Sample Payload
201
202```json
203{
204    "Name": "minikube",
205    "Description": "updated name",
206    "Config": {
207        "Host": "https://192.0.2.42:8443",
208        "CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
209        "ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
210    }
211}
212```
213
214### Sample Request
215
216```sh
217$ curl -X PUT \
218    --data @payload.json \
219    http://127.0.0.1:8500/v1/acl/auth-method/minikube
220```
221
222### Sample Response
223
224```json
225{
226    "Name": "minikube",
227    "Description": "updated name",
228    "Type": "kubernetes",
229    "Config": {
230        "Host": "https://192.0.2.42:8443",
231        "CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n",
232        "ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..."
233    },
234    "CreateIndex": 15,
235    "ModifyIndex": 224
236}
237```
238
239## Delete an Auth Method
240
241This endpoint deletes an ACL auth method.
242
243~> Deleting an auth method will also immediately delete all associated
244[binding rules](/api/acl/binding-rules.html) as well as any
245outstanding [tokens](/api/acl/tokens.html) created from this auth method.
246
247| Method   | Path                      | Produces                   |
248| -------- | ------------------------- | -------------------------- |
249| `DELETE` | `/acl/auth-method/:name`  | `application/json`         |
250
251Even though the return type is application/json, the value is either true or
252false indicating whether the delete succeeded.
253
254The table below shows this endpoint's support for
255[blocking queries](/api/features/blocking.html),
256[consistency modes](/api/features/consistency.html),
257[agent caching](/api/features/caching.html), and
258[required ACLs](/api/index.html#authentication).
259
260| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
261| ---------------- | ----------------- | ------------- | ------------ |
262| `NO`             | `none`            | `none`        | `acl:write`  |
263
264### Parameters
265
266- `name` `(string: <required>)` - Specifies the name of the ACL auth method to
267  delete. This is required and is specified as part of the URL path.
268
269- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace of the
270  Auth Method to delete. This value can be specified as the `ns` URL query
271  parameter or in the `X-Consul-Namespace` header. If not provided by either,
272  the namespace will be inherited from the request's ACL token or will default
273  to the `default` namespace. Added in Consul 1.7.0.
274
275### Sample Request
276
277```sh
278$ curl -X DELETE \
279    http://127.0.0.1:8500/v1/acl/auth-method/minikube
280```
281
282### Sample Response
283
284```json
285true
286```
287
288## List Auth Methods
289
290This endpoint lists all the ACL auth methods.
291
292| Method | Path                         | Produces                   |
293| ------ | ---------------------------- | -------------------------- |
294| `GET`  | `/acl/auth-methods`          | `application/json`         |
295
296The table below shows this endpoint's support for
297[blocking queries](/api/features/blocking.html),
298[consistency modes](/api/features/consistency.html),
299[agent caching](/api/features/caching.html), and
300[required ACLs](/api/index.html#authentication).
301
302| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
303| ---------------- | ----------------- | ------------- | ------------ |
304| `YES`            | `all`             | `none`        | `acl:read`   |
305
306### Parameters
307
308- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to list
309  the auth methods for. This value can be specified as the `ns` URL query
310  parameter or in the `X-Consul-Namespace` header. If not provided by either,
311  the namespace will be inherited from the request's ACL token or will default
312  to the `default` namespace. The namespace may be specified as '*' and then
313  results will be returned for all namespaces. Added in Consul 1.7.0.
314
315
316## Sample Request
317
318```sh
319$ curl -X GET http://127.0.0.1:8500/v1/acl/auth-methods
320```
321
322### Sample Response
323
324-> **Note** - The contents of the `Config` field are not included in the
325listing and must be retrieved by the [auth method reading endpoint](#read-an-auth-method).
326
327```json
328[
329    {
330        "Name": "minikube-1",
331        "Type": "kubernetes",
332        "Description": "",
333        "CreateIndex": 14,
334        "ModifyIndex": 14
335    },
336    {
337        "Name": "minikube-2",
338        "Type": "kubernetes",
339        "Description": "",
340        "CreateIndex": 15,
341        "ModifyIndex": 15
342    }
343]
344```
345