List user accounts
GET /admin/users
Lists the user accounts on this instance, newest first, with each
account’s status, sign-in lockout state and contact details. Search
with q and filter with status; without status, every status is
listed, archived included.
You need users.read (system.admin also works). Full names and
email addresses are included whenever an account has them, with no
further check: users.pii.read only covers session IP addresses,
which this list doesn’t return.
Pass next_cursor back as cursor to get the next page. A status
other than the four values, or a cursor the server can’t read,
gets 500 rather than 400.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”Text to find in the username, full name or email address, ignoring case. Display names aren’t searched, and % and _ act as wildcards. Spaces at either end are ignored, and an empty value means no search.
Show only accounts with this status. Leave it out to list every status. Any other value, including an empty one, gets 500.
The next_cursor from the previous page. A cursor the server can’t read gets 500.
How many accounts to return, from 1 to 200. Other values aren’t rejected: anything above 200 counts as 200, and 0 or less as 50.
Responses
Section titled “ Responses ”A page of accounts.
object
One account in the admin user directory. Passwords and keys aren’t included.
object
The account’s number, used as {ref} in the other /admin/users/{ref} endpoints.
The name the account signs in with. Empty if the account has none.
The full name on the account. Left out when there’s none.
The email address on the account. Left out when there’s none.
The name to show: the profile’s display name if it has one, otherwise the full name, otherwise the username.
The avatar URL stored on the user’s profile; left out when none is stored.
The account’s status. Change it with PUT /admin/users/{ref}/status, whose page explains each one.
One of the account’s instance-wide roles: the first by name, or an empty string if it has none. Roles held within a team aren’t counted, and the account may have other roles too.
When the account was created. An account with no recorded creation time shows 0001-01-01T00:00:00Z, is listed last, and is left out of every page after the first.
The last recorded start of a session for the account, usually a sign-in. It’s updated on a best-effort basis when a session starts, so it can miss one, and using an API token or an open session doesn’t change it. Left out if it has never been set.
When the account expires; left out if it doesn’t. After that time it can’t sign in, but sessions and API tokens it already has keep working.
When the account’s sign-in lockout ends. While this time is in the
future, sign-in is refused. A time in the past means the lockout is
over; it stays until a successful sign-in or POST /admin/users/{ref}/unlock-account clears it. Left out when no
lockout is recorded.
Wrong passwords entered since the last successful sign-in or unlock; attempts while the account is locked aren’t counted. Reaching the instance’s limit (5 by default) locks the account. The count isn’t reset when a lockout ends, so the next wrong password locks it again.
The sign-in provider recorded for the account, if any. Accounts created by this app don’t record one, so it’s normally left out; LDAP and SAML sign-in aren’t available today.
The instance the account’s profile came from, when it was received from a federated instance. Left out for profiles from this instance and accounts without a profile.
How many accounts match q and status in all, ignoring the cursor. It’s counted separately from the page, so changes made in between can make the two disagree.
Pass this as cursor to get the next page. Left out on the last
page.
Authentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completedUnexpected server error
object
Human-readable error summary
Example
the request could not be completed