--- layout: api page_title: ACL Auth Methods - HTTP API sidebar_title: Auth Methods description: The /acl/auth-method endpoints manage Consul's ACL Auth Methods. --- # ACL Auth Method HTTP API -> **1.5.0+:** The auth method APIs are available in Consul versions 1.5.0 and newer. The `/acl/auth-method` endpoints [create](#create-an-auth-method), [read](#read-an-auth-method), [update](#update-an-auth-method), [list](#list-auth-methods) and [delete](#delete-an-auth-method) ACL auth methods in Consul. For more information on how to setup ACLs, please see the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/production-acls). ## Create an Auth Method This endpoint creates a new ACL auth method. | Method | Path | Produces | | ------ | ------------------ | ------------------ | | `PUT` | `/acl/auth-method` | `application/json` | The table below shows this endpoint's support for [blocking queries](/api/features/blocking), [consistency modes](/api/features/consistency), [agent caching](/api/features/caching), and [required ACLs](/api#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `acl:write` | ### Payload Fields - `Name` `(string: )` - Specifies a name for the ACL auth method. The name can contain alphanumeric characters, dashes `-`, and underscores `_`. This field is immutable and must be unique. - `Type` `(string: )` - The type of auth method being configured. This field is immutable. For allowed values see the [auth method documentation](/docs/acl/auth-methods). - `Description` `(string: "")` - Free form human readable description of the auth method. - `DisplayName` `(string: "")` - An optional name to use instead of the `Name` field when displaying information about this auth method. Added in Consul 1.8.0. - `MaxTokenTTL` `(duration: 0s)` - This specifies the maximum life of any token created by this auth method. When set it will initialize the [`ExpirationTime`](/api/acl/tokens.html#expirationtime) field on all tokens to a value of `Token.CreateTime + AuthMethod.MaxTokenTTL`. This field is not persisted beyond its initial use. Can be specified in the form of `"60s"` or `"5m"` (i.e., 60 seconds or 5 minutes, respectively). This value must be no smaller than 1 minute and no longer than 24 hours. Added in Consul 1.8.0. This must be set to a nonzero value for `type=oidc`. - `Config` `(map[string]string: )` - The raw configuration to use for the chosen auth method. Contents will vary depending upon the type chosen. For more information on configuring specific auth method types, see the [auth method documentation](/docs/acl/auth-methods). - `Namespace` `(string: "")` - Specifies the namespace to create the auth method within. If not provided in the JSON body, the value of the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. If not provided at all, the namespace will be inherited from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0. - `NamespaceRules` `(array)` - A set of rules that can control which namespace tokens created via this auth method will be created within. Note that assigning namespaces via rules requires the auth method to reside within the `default` namespace. Unlike binding rules, the **first** matching namespace rule wins. Added in Consul 1.8.0. - `Selector` `(string: "")` - Specifies the expression used to match this namespace rule against valid identities returned from an auth method validation. If empty this namespace rule matches all valid identities returned from the auth method. For example: ```text serviceaccount.namespace==default and serviceaccount.name!=vault ``` - `BindNamespace` `(string: )` - If the namespace rule's `Selector` matches then this is used to control the namespace where the token is created. This can either be a plain string or lightly templated using [HIL syntax](https://github.com/hashicorp/hil) to interpolate the same values that are usable by the `Selector` syntax. For example: ```text prefixed-${serviceaccount.name} ``` ### Sample Payload ```json { "Name": "minikube", "Type": "kubernetes", "Description": "dev minikube cluster", "Config": { "Host": "https://192.0.2.42:8443", "CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n", "ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..." } } ``` ### Sample Request ```shell $ curl -X PUT \ --data @payload.json \ http://127.0.0.1:8500/v1/acl/auth-method ``` ### Sample Response ```json { "Name": "minikube", "Type": "kubernetes", "Description": "dev minikube cluster", "Config": { "Host": "https://192.0.2.42:8443", "CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n", "ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..." }, "CreateIndex": 15, "ModifyIndex": 15 } ``` ## Read an Auth Method This endpoint reads an ACL auth method with the given name. If no auth method exists with the given name, a 404 is returned instead of a 200 response. | Method | Path | Produces | | ------ | ------------------------ | ------------------ | | `GET` | `/acl/auth-method/:name` | `application/json` | The table below shows this endpoint's support for [blocking queries](/api/features/blocking), [consistency modes](/api/features/consistency), [agent caching](/api/features/caching), and [required ACLs](/api#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `YES` | `all` | `none` | `acl:read` | ### Parameters - `name` `(string: )` - Specifies the name of the ACL auth method to read. This is required and is specified as part of the URL path. - `ns` `(string: "")` - Specifies the namespace to lookup the auth method within. This value can be specified as the `ns` URL query parameter or in the `X-Consul-Namespace` header. If not provided by either, the namespace will be inherited from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0. ### Sample Request ```shell $ curl -X GET http://127.0.0.1:8500/v1/acl/auth-method/minikube ``` ### Sample Response ```json { "Name": "minikube", "Type": "kubernetes", "Description": "dev minikube cluster", "Config": { "Host": "https://192.0.2.42:8443", "CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n", "ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..." }, "CreateIndex": 15, "ModifyIndex": 224 } ``` ## Update an Auth Method This endpoint updates an existing ACL auth method. | Method | Path | Produces | | ------ | ------------------------ | ------------------ | | `PUT` | `/acl/auth-method/:name` | `application/json` | The table below shows this endpoint's support for [blocking queries](/api/features/blocking), [consistency modes](/api/features/consistency), [agent caching](/api/features/caching), and [required ACLs](/api#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `acl:write` | ### Parameters - `Name` `(string: )` - Specifies the name of the auth method to update. This is required in the URL path but may also be specified in the JSON body. If specified in both places then they must match exactly. - `Type` `(string: )` - Specifies the type of the auth method being updated. This field is immutable so if present in the body then it must match the existing value. If not present then the value will be filled in by Consul. - `Description` `(string: "")` - Free form human readable description of the auth method. - `DisplayName` `(string: "")` - An optional name to use instead of the `Name` field when displaying information about this auth method. Added in Consul 1.8.0. - `MaxTokenTTL` `(duration: 0s)` - This specifies the maximum life of any token created by this auth method. When set it will initialize the [`ExpirationTime`](/api/acl/tokens.html#expirationtime) field on all tokens to a value of `Token.CreateTime + AuthMethod.MaxTokenTTL`. This field is not persisted beyond its initial use. Can be specified in the form of `"60s"` or `"5m"` (i.e., 60 seconds or 5 minutes, respectively). This value must be no smaller than 1 minute and no longer than 24 hours. Added in Consul 1.8.0. This must be set to a nonzero value for `type=oidc`. - `Config` `(map[string]string: )` - The raw configuration to use for the chosen auth method. Contents will vary depending upon the type chosen. For more information on configuring specific auth method types, see the [auth method documentation](/docs/acl/auth-methods). - `Namespace` `(string: "")` - Specifies the namespace of the auth method to update. If not provided in the JSON body, the value of the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. If not provided at all, the namespace will be inherited from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0. - `NamespaceRules` `(array)` - A set of rules that can control which namespace tokens created via this auth method will be created within. Note that assigning namespaces via rules requires the auth method to reside within the `default` namespace. Unlike binding rules, the **first** matching namespace rule wins. Added in Consul 1.8.0. - `Selector` `(string: "")` - Specifies the expression used to match this namespace rule against valid identities returned from an auth method validation. If empty this namespace rule matches all valid identities returned from the auth method. For example: ```text serviceaccount.namespace==default and serviceaccount.name!=vault ``` - `BindNamespace` `(string: )` - If the namespace rule's `Selector` matches then this is used to control the namespace where the token is created. This can either be a plain string or lightly templated using [HIL syntax](https://github.com/hashicorp/hil) to interpolate the same values that are usable by the `Selector` syntax. For example: ```text prefixed-${serviceaccount.name} ``` ### Sample Payload ```json { "Name": "minikube", "Description": "updated name", "Config": { "Host": "https://192.0.2.42:8443", "CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n", "ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..." } } ``` ### Sample Request ```shell $ curl -X PUT \ --data @payload.json \ http://127.0.0.1:8500/v1/acl/auth-method/minikube ``` ### Sample Response ```json { "Name": "minikube", "Description": "updated name", "Type": "kubernetes", "Config": { "Host": "https://192.0.2.42:8443", "CACert": "-----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n", "ServiceAccountJWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9..." }, "CreateIndex": 15, "ModifyIndex": 224 } ``` ## Delete an Auth Method This endpoint deletes an ACL auth method. ~> Deleting an auth method will also immediately delete all associated [binding rules](/api/acl/binding-rules) as well as any outstanding [tokens](/api/acl/tokens) created from this auth method. | Method | Path | Produces | | -------- | ------------------------ | ------------------ | | `DELETE` | `/acl/auth-method/:name` | `application/json` | Even though the return type is application/json, the value is either true or false indicating whether the delete succeeded. The table below shows this endpoint's support for [blocking queries](/api/features/blocking), [consistency modes](/api/features/consistency), [agent caching](/api/features/caching), and [required ACLs](/api#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `acl:write` | ### Parameters - `name` `(string: )` - Specifies the name of the ACL auth method to delete. This is required and is specified as part of the URL path. - `ns` `(string: "")` - Specifies the namespace of the Auth Method to delete. This value can be specified as the `ns` URL query parameter or in the `X-Consul-Namespace` header. If not provided by either, the namespace will be inherited from the request's ACL token or will default to the `default` namespace. Added in Consul 1.7.0. ### Sample Request ```shell $ curl -X DELETE \ http://127.0.0.1:8500/v1/acl/auth-method/minikube ``` ### Sample Response ```json true ``` ## List Auth Methods This endpoint lists all the ACL auth methods. | Method | Path | Produces | | ------ | ------------------- | ------------------ | | `GET` | `/acl/auth-methods` | `application/json` | The table below shows this endpoint's support for [blocking queries](/api/features/blocking), [consistency modes](/api/features/consistency), [agent caching](/api/features/caching), and [required ACLs](/api#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `YES` | `all` | `none` | `acl:read` | ### Parameters - `ns` `(string: "")` - Specifies the namespace to list the auth methods for. This value can be specified as the `ns` URL query parameter or in the `X-Consul-Namespace` header. If not provided by either, the namespace will be inherited from the request's ACL token or will default to the `default` namespace. The namespace may be specified as '\*' and then results will be returned for all namespaces. Added in Consul 1.7.0. ## Sample Request ```shell $ curl -X GET http://127.0.0.1:8500/v1/acl/auth-methods ``` ### Sample Response -> **Note** - The contents of the `Config` field are not included in the listing and must be retrieved by the [auth method reading endpoint](#read-an-auth-method). ```json [ { "Name": "minikube-1", "Type": "kubernetes", "Description": "", "CreateIndex": 14, "ModifyIndex": 14 }, { "Name": "minikube-2", "Type": "kubernetes", "Description": "", "CreateIndex": 15, "ModifyIndex": 15 } ] ```