/sys/locked-users

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

Refer to the user lockout overview for more details about how Vault handles lockouts.

List locked users

Restricted endpoint

The API path can only be called from the root or administrative namespace.

The list endpoint returns information on the users currently locked by 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 includes locked users in all child namespaces of the namespace in which the request was made.

Sample request

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

Sample response

{
   "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:

{
   "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

{
  "mount_accessor": "auth_userpass_af8d1d32"
}

Sample request

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

Unlock user

Restricted endpoint

The API path can only be called from the root or administrative namespace.

The unlock user endpoint frees a locked user with the provided mount_accessor and alias_identifier in the given namespace. The unlock command is idempotent. Calls to the endpoint succeed even if the user matching the provided mount_accessor and alias_identifier is not currently 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) - 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

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