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