vault/website/content/api-docs/system/user-lockout.mdx

---
layout: api
page_title: /sys/locked-users - HTTP API
description: The `/sys/locked-users` endpoint is used to manage locked users in Vault.
---

# `/sys/locked-users`

The `/sys/locked-users` endpoint is used to list and unlock locked users in Vault. 

Please visit [user lockout](/docs/concepts/user-lockout) concepts page for more details about the feature. 

## List Locked Users

This endpoint lists the locked users information in Vault. 

The response will include all child namespaces of the namespace in which the
request was made. If some namespace has subsequently been deleted, its path will
be listed as "deleted namespace :ID:." Deleted namespaces are reported only for
queries in the root namespace because the information about the namespace path
is unknown. The response will be returned in the decreasing order of locked user
counts. 

This endpoint was added in Vault 1.13.

| Method | Path             |
| :----- | :--------------- |
| `GET` | `/sys/locked-users` |

### Parameters

- `mount_accessor` `(string, optional)` -  Specifies the identifier of the auth mount entry to which the user
belongs in the namespace in which the request was made. If no mount accessor is specified,
the response will include locked users in all child namespaces of the namespace in which the request was made. 

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/sys/locked-users
```

### Sample Response

```json
{
   "request_id":"26be5ab9-dcac-9237-ec12-269a8ca647d5",
   "lease_id":"",
   "renewable":false,
   "lease_duration":0,
   "data":{
      "by_namespace":[
         {
            "namespace_id":"BzIex",
            "namespace_path":"ns1/",
            "counts": 3,
            "mount_accessors":[
               {
                  "mount_accessor":"auth_userpass_79e2fe02",
                  "counts":3,
                  "alias_identifiers":[
                      {"user3"},
                      {"user4"},
                      {"user5"},
                  ]
               },
            ]
         },
         {
            "namespace_id":"root",
            "namespace_path":"",
            "counts":2,
            "mount_accessors":[
               {
                  "mount_accessor":"auth_userpass_837f35fc",
                  "counts":2,
                  "alias_identifiers":[
                      {"user1"},
                      {"user2"}
                  ]
               },
            ]
         },
          {
            "namespace_id":"v1lb9",
            "namespace_path":"ns1/ns2/",
            "counts":1,
            "mount_accessors":[
               {
                  "mount_accessor":"auth_userpass_af8d1d32",
                  "counts":1,
                  "alias_identifiers":[
                      {"user6"}
                  ]
               },
            ]
         }
      ],
      "total":6
   },
   "wrap_info":null,
   "warnings":null,
   "auth":null
}
```

For deleted namespaces, the response will look like:

```json
{
   "request_id":"26be5ab9-dcac-9237-ec12-269a8ca647d5",
   "lease_id":"",
   "renewable":false,
   "lease_duration":0,
   "data":{
      "by_namespace":[
         {
            "namespace_id":"BzIex",
            "namespace_path":"ns1/",
            "counts": 3,
            "mount_accessors":[
               {
                  "mount_accessor":"auth_userpass_79e2fe02",
                  "counts":3,
                  "alias_identifiers":[
                      {"user3"},
                      {"user4"},
                      {"user5"},
                  ]
               },
            ]
         },
         {
            "namespace_id":"root",
            "namespace_path":"",
            "counts":2,
            "mount_accessors":[
               {
                  "mount_accessor":"auth_userpass_837f35fc",
                  "counts":2,
                  "alias_identifiers":[
                      {"user1"},
                      {"user2"}
                  ]
               },
            ]
         },
          {
            "namespace_id":"v1lb9",
            "namespace_path":"deleted namespace v1lb9",
            "counts":1,
            "mount_accessors":[
               {
                  "mount_accessor":"auth_userpass_af8d1d32",
                  "counts":1,
                  "alias_identifiers":[
                      {"user6"}
                  ]
               },
            ]
         }
      ],
      "total":6
   },
   "wrap_info":null,
   "warnings":null,
   "auth":null
}
```


### Sample request with mount accessor

#### Sample Payload

```json
{
  "mount_accessor": "auth_userpass_af8d1d32"
}
```

#### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --data @payload.json \
    --request GET \
    http://127.0.0.1:8200/v1/sys/locked-users
```

## Unlock User

This endpoint unlocks a locked user with provided mount_accessor and alias_identifier in namespace in which the request was made if locked. 
This command is idempotent, meaning it succeeds even if user with the given mount_accessor and alias_identifier is not locked. 
 

This endpoint was added in Vault 1.13.

| Method | Path             |
| :----- | :--------------- |
| `POST` | `/sys/locked-users/:mount_accessor/unlock/:alias-identifier` |

### Parameters

- `mount_accessor` `(string, required)` - Specifies the identifier of the auth mount entry to which the user
belongs
- `alias_identifier` `(string, required)` - It is the name of the alias (user). For example, if the alias 
belongs to userpass backend, the name should be a valid username within userpass auth method. If the alias belongs
to an approle auth method, the name should be a valid RoleID. If the alias belongs to an ldap auth method, the name
should be a valid username.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/sys/locked-users/auth_userpass_af8d1d32/unlock/bsmith
```