Grants or removes the administrator flag.
Why the last one cannot be removed
An instance with no administrator cannot be repaired through the API: no endpoint is left that would grant the flag back. The way out is the command line against the database file, which an operator locked out of a container may not have.
Removing your own flag while another administrator still holds it is allowed. That is stepping down, not an accident.
Errors
401 when nothing was signed in, 403 when the caller is not an
administrator or used a bearer token, 404 when no account has that
identifier, 409 when this would leave the instance with none.
sessiontessera_session<token>Set by POST /auth/login. A browser sends it automatically; it is HttpOnly, so page scripts cannot read or set it.
id*stringWhich account to change
application/json- body
Body of PATCH /admin/users/{id}.
is_admin?|Whether this account administers the instance.
Omit to leave the role unchanged. Sending it always rewrites the role
(true to owner, false to none), so a client changing only state
or a quota must omit it, or it demotes the account as a side effect.
max_file_bytes?|Largest single file this one account may send, overriding its role's.
Absent leaves it alone, null clears it so the role's applies again,
and 0 gives this account no limit of its own.
server.max_body_bytes still applies on top; this cannot raise it.
quota_bytes?|Largest single file this one account may send, overriding its role's.
Absent leaves it alone, null clears it so the role's applies again,
and 0 gives this account no limit of its own.
server.max_body_bytes still applies on top; this cannot raise it.
state?|active to let it in, disabled to suspend it.
Omitted leaves it as it is. deleted is refused here: removing an
account scrubs it: DELETE, not a field on a patch.
The account as it now stands
application/json- response
One account, as an administrator sees it.
What a user sees of themselves, plus the one thing only an administrator
needs: whether the account may sign in. Users never see their own state
as anything but active, since a disabled account cannot sign in to ask.
email*stringNormalised address.
email_verified_at?|When the address was last proven to reach this user, or null if never.
Set by confirming a registration, by a provider vouching for the
address, or by following the link from
POST /account/email/verification. Cleared when the address changes.
date-timehas_password*booleanWhether the account has a password.
An account created through GitHub, Discord or OIDC has none. It confirms
changes by having signed in within the last few minutes instead of by
typing one, so a client shows a password field only when this is
true; see reauthentication_required.
id*stringStable identifier.
is_admin*booleanWhether the account holds the seeded administrator role.
Kept because clients read it, but derived and not stored, and narrower
than permissions. An account in a role granting users:read
and nothing else is not an administrator, yet reaches one administrative
endpoint. New clients should read permissions.
must_change_password*booleanWhether the account must set a new password before doing anything else.
Set on the administrator generated at first run. A client seeing this should send the user to a change-password screen and nowhere else.
permissions*array<string>Everything this account is allowed to do.
resource:verb strings, and what a client should decide from. A screen
guessing from is_admin is wrong for every role between "member" and
"everything".
quota_bytes?|A storage quota set on this one account, overriding its role's.
null means the role's applies; 0 means this account has no ceiling
of its own. What is actually left is storage_remaining_bytes on
/capabilities, which accounts for what has been used.
int640 <= valueroles*array<string>The roles it is in, by name.
username*stringNormalised account name.
max_file_bytes?|Largest single file for this account, overriding its role's limit.
null means the role's limit applies; 0 means no limit for this
account. Only administrators see it; what a user may actually send is
max_upload_bytes on /capabilities.
int640 <= valuemfa_enabled*booleanWhether signing in with the password asks this account for a code.
So the panel can offer DELETE /admin/users/{id}/mfa only where there
is something to turn off.
state*UserStateWhether it may sign in, or has been deleted.
"active""disabled""deleted"curl -X PATCH 'https://example.com/api/v1/admin/users/string' \ -H 'Content-Type: application/json' \ -d '{}'{ "email": "string", "email_verified_at": "2019-08-24T14:15:22Z", "has_password": true, "id": "string", "is_admin": true, "must_change_password": true, "permissions": [ "string" ], "quota_bytes": 0, "roles": [ "string" ], "username": "string", "max_file_bytes": 0, "mfa_enabled": true, "state": "active"}