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