1---
2layout: "api"
3page_title: "/sys/auth - HTTP API"
4sidebar_title: "<code>/sys/auth</code>"
5sidebar_current: "api-http-system-auth"
6description: |-
7  The `/sys/auth` endpoint is used to manage auth methods in Vault.
8---
9
10# `/sys/auth`
11
12The `/sys/auth` endpoint is used to list, create, update, and delete auth
13methods. Auth methods convert user or machine-supplied information into a
14token which can be used for all future requests.
15
16## List Auth Methods
17
18This endpoint lists all enabled auth methods.
19
20| Method   | Path                         |
21| :--------------------------- | :--------------------- |
22| `GET`    | `/sys/auth`                  |
23
24### Sample Request
25
26```
27$ curl \
28    --header "X-Vault-Token: ..." \
29    http://127.0.0.1:8200/v1/sys/auth
30```
31
32### Sample Response
33
34```json
35{
36  "github/": {
37    "type": "github",
38    "description": "GitHub auth"
39  },
40  "token/": {
41    "config": {
42      "default_lease_ttl": 0,
43      "max_lease_ttl": 0
44    },
45    "description": "token based credentials",
46    "type": "token"
47  }
48}
49```
50
51## Enable Auth Method
52
53This endpoint enables a new auth method. After enabling, the auth method can
54be accessed and configured via the auth path specified as part of the URL. This
55auth path will be nested under the `auth` prefix.
56
57For example, enable the "foo" auth method will make it accessible at
58`/auth/foo`.
59
60- **`sudo` required** – This endpoint requires `sudo` capability in addition to
61  any path-specific capabilities.
62
63| Method   | Path                         |
64| :--------------------------- | :--------------------- |
65| `POST`   | `/sys/auth/:path`            |
66
67### Parameters
68
69- `path` `(string: <required>)` – Specifies the path in which to enable the auth
70  method. This is part of the request URL.
71
72    !> **NOTE:** Use ASCII printable characters to specify the desired path.
73
74- `description` `(string: "")` – Specifies a human-friendly description of the
75  auth method.
76
77- `type` `(string: <required>)` – Specifies the name of the authentication
78  method type, such as "github" or "token".
79
80- `config` `(map<string|string>: nil)` – Specifies configuration options for
81  this auth method. These are the possible values:
82
83  - `default_lease_ttl` `(string: "")` - The default lease duration, specified
84    as a string duration like "5s" or "30m".
85
86  - `max_lease_ttl` `(string: "")` - The maximum lease duration, specified as a
87    string duration like "5s" or "30m".
88
89  - `audit_non_hmac_request_keys` `(array: [])` - Comma-separated list of keys
90    that will not be HMAC'd by audit devices in the request data object.
91
92  - `audit_non_hmac_response_keys` `(array: [])` - Comma-separated list of keys
93    that will not be HMAC'd by audit devices in the response data object.
94
95  - `listing_visibility` `(string: "")` - Specifies whether to show this mount
96    in the UI-specific listing endpoint.
97
98  - `passthrough_request_headers` `(array: [])` - Comma-separated list of headers
99    to whitelist and pass from the request to the plugin.
100
101  - `allowed_response_headers` `(array: [])` - Comma-separated list of headers
102    to whitelist, allowing a plugin to include them in the response.
103
104Additionally, the following options are allowed in Vault open-source, but
105relevant functionality is only supported in Vault Enterprise:
106
107- `local` `(bool: false)` – Specifies if the auth method is local only. Local
108  auth methods are not replicated nor (if a secondary) removed by replication.
109
110  ~> ** Warning:** Remember, policies when using replication secondaries are
111  validated by the local cluster. An administrator that can set up a local auth
112  method mount can assign policies to tokens that are valid on the replication
113  primary if a request is forwarded. Never give untrusted administrators the
114  ability to assign policies or configure authentication methods.
115
116- `seal_wrap` `(bool: false)` - Enable seal wrapping for the mount, causing
117  values stored by the mount to be wrapped by the seal's encryption capability.
118
119### Sample Payload
120
121```json
122{
123  "type": "github",
124  "description": "Login with GitHub"
125}
126```
127
128### Sample Request
129
130```
131$ curl \
132    --header "X-Vault-Token: ..." \
133    --request POST \
134    --data @payload.json \
135    http://127.0.0.1:8200/v1/sys/auth/my-auth
136```
137
138## Disable Auth Method
139
140This endpoint disables the auth method at the given auth path.
141
142- **`sudo` required** – This endpoint requires `sudo` capability in addition to
143  any path-specific capabilities.
144
145| Method   | Path                         |
146| :--------------------------- | :--------------------- |
147| `DELETE` | `/sys/auth/:path`            |
148
149### Parameters
150
151- `path` `(string: <required>)` – Specifies the path to disable. This is part of
152  the request URL.
153
154### Sample Request
155
156```
157$ curl \
158    --header "X-Vault-Token: ..." \
159    --request DELETE \
160    http://127.0.0.1:8200/v1/sys/auth/my-auth
161```
162
163## Read Auth Method Tuning
164
165This endpoint reads the given auth path's configuration. _This endpoint requires
166`sudo` capability on the final path, but the same functionality can be achieved
167without `sudo` via `sys/mounts/auth/[auth-path]/tune`._
168
169- **`sudo` required** – This endpoint requires `sudo` capability in addition to
170  any path-specific capabilities.
171
172| Method   | Path                         |
173| :--------------------------- | :--------------------- |
174| `GET`    | `/sys/auth/:path/tune`       |
175
176### Parameters
177
178- `path` `(string: <required>)` – Specifies the path in which to tune.
179
180### Sample Request
181
182```
183$ curl \
184    --header "X-Vault-Token: ..." \
185    http://127.0.0.1:8200/v1/sys/auth/my-auth/tune
186```
187
188### Sample Response
189
190```json
191{
192  "default_lease_ttl": 3600,
193  "max_lease_ttl": 7200
194}
195```
196
197## Tune Auth Method
198
199Tune configuration parameters for a given auth path. _This endpoint
200requires `sudo` capability on the final path, but the same functionality
201can be achieved without `sudo` via `sys/mounts/auth/[auth-path]/tune`._
202
203- **`sudo` required** – This endpoint requires `sudo` capability in addition to
204  any path-specific capabilities.
205
206| Method   | Path                         |
207| :--------------------------- | :--------------------- |
208| `POST`   | `/sys/auth/:path/tune`       |
209
210### Parameters
211
212- `default_lease_ttl` `(int: 0)` – Specifies the default time-to-live. If set on
213  a specific auth path, this overrides the global default.
214
215- `max_lease_ttl` `(int: 0)` – Specifies the maximum time-to-live. If set on a
216  specific auth path, this overrides the global default.
217
218- `description` `(string: "")` – Specifies the description of the mount. This
219  overrides the current stored value, if any.
220
221- `audit_non_hmac_request_keys` `(array: [])` - Specifies the comma-separated
222  list of keys that will not be HMAC'd by audit devices in the request data
223  object.
224
225- `audit_non_hmac_response_keys` `(array: [])` - Specifies the comma-separated
226  list of keys that will not be HMAC'd by audit devices in the response data
227  object.
228
229- `listing_visibility` `(string: "")` - Specifies whether to show this mount
230   in the UI-specific listing endpoint. Valid values are `"unauth"` or `""`.
231
232- `passthrough_request_headers` `(array: [])` - Comma-separated list of headers
233  to whitelist and pass from the request to the plugin.
234
235- `allowed_response_headers` `(array: [])` - Comma-separated list of headers
236  to whitelist, allowing a plugin to include them in the response.
237
238- `token_type` `(string: "")` – Specifies the type of tokens that should be
239  returned by the mount. The following values are available:
240
241  - `default-service`: Unless the auth method requests a different type, issue
242    service tokens
243  - `default-batch`: Unless the auth method requests a different type, issue
244    batch tokens
245  - `service`: Override any auth method preference and always issue service
246    tokens from this mount
247  - `batch`: Override any auth method preference and always issue batch tokens
248    from this mount
249
250### Sample Payload
251
252```json
253{
254  "default_lease_ttl": 1800,
255  "max_lease_ttl": 86400
256}
257```
258
259### Sample Request
260
261```
262$ curl \
263    --header "X-Vault-Token: ..." \
264    --request POST \
265    --data @payload.json \
266    http://127.0.0.1:8200/v1/sys/auth/my-auth/tune
267```
268