/api/v1/user
GET /user — List all users visible to the authenticated user.
GET /user — List all users visible to the authenticated user.Differs from easydb 5: listing requires only an authenticated
session, not the system.user read right. The filter parameter is
group_ids (easydb 5: groupids) and the default limit is 100
(easydb 5: default and maximum 1000).
Access token in the Authorization header:
Authorization: Bearer <token>.
Maximum number of users to return. Defaults to 100 when omitted
or not positive.
100Number of users to skip from the start of the result.
Comma-separated list of group _ids; returns only users that are
members of one of the given groups.
Comma-separated list of user types to filter by (for example
easydb).
ISO-8601 timestamp; returns only users whose _updated_at is at or
after this time.
ISO-8601 timestamp, or the literal null. With null, only
non-archived users are returned. Otherwise returns users whose
_archived_at is at or after the given time.
If true, each entry includes the stored password hash (for
backup tooling). Requires system.root.
Array of all users visible to the current session.
A user record. Used as the request and response body of the
/api/v1/user* endpoints.
Fixed marker identifying this object as a user.
Plaintext password (write-only). Set on user creation to seed a
password; otherwise use POST /user/change_password. Never echoed
back in responses.
The stored password hash. Only returned when include_password=true
is set and the requester holds system.root — used by backup
tooling.
UTC time the user was created.
UTC time the user was last updated.
UTC time the user was archived. Archived users cannot sign in
(login fails with LoginUserArchived) and cannot be modified.
UTC time of the user's most recent activity.
No authenticated user. The request must carry a valid access token.
The authenticated user is not allowed to perform the operation. The exact condition depends on the operation:
GET /user: only wheninclude_password=trueand the requester lackssystem.root— codeSystemRightRequired.GET /user/{id}: wheninclude_password=trueand the requester lackssystem.root(SystemRightRequired); or when a non-system.rootrequester neither owns the target user nor holds the per-userreadACL right — codeRightRequired.POST/PUT /user: when a non-system.rootrequester lacks the ACL right needed to create or modify a targeted user (linking/unlinking groups, writing another user, or changing an owner) — codeRightRequired. Other save-right violations (for example modifying a protected field of your own record) are reported as400, not403.DELETE /user/{id}: when the requester holds neithersystem.usernorsystem.root(SystemRightRequired); or when asystem.user-but-not-system.rootrequester lacks the per-userdeleteACL right on the target — codeRightRequired.POST /user/change_password: when the requester lacks thesystem.user.change_passwordsystem right (orsystem.root) — codeSystemRightRequired; or when the new password fails the configured complexity rules — codePasswordRequirementNotFulfilled(theerrormessage carries the configured password hint).
POST /user — Create or update one or more users.
POST /user — Create or update one or more users.The payload is an array of user objects. Users with _id set are
updated; users without _id are created. The response carries the
saved users.
Differs from easydb 5: POST and PUT are aliases and both create
and update; create vs. update is decided by the presence of _id. In
easydb 5 PUT /api/v1/user only creates, POST /api/v1/user only
updates, and an update must carry the current _version.
Access token in the Authorization header:
Authorization: Bearer <token>.
Set to ignore_password_requirements to re-submit a request that
was answered with a 202 because a password did not satisfy the
configured complexity rules, saving the user anyway (see the 202
response).
If true, skip email-format validation on the saved users.
Allowed only with system.root; without it the request fails
with a 400 (code ServerGeneric).
A user record. Used as the request and response body of the
/api/v1/user* endpoints.
Fixed marker identifying this object as a user.
Plaintext password (write-only). Set on user creation to seed a
password; otherwise use POST /user/change_password. Never echoed
back in responses.
The stored password hash. Only returned when include_password=true
is set and the requester holds system.root — used by backup
tooling.
UTC time the user was created.
UTC time the user was last updated.
UTC time the user was archived. Archived users cannot sign in
(login fails with LoginUserArchived) and cannot be modified.
UTC time of the user's most recent activity.
The users were saved.
A user record. Used as the request and response body of the
/api/v1/user* endpoints.
Fixed marker identifying this object as a user.
Plaintext password (write-only). Set on user creation to seed a
password; otherwise use POST /user/change_password. Never echoed
back in responses.
The stored password hash. Only returned when include_password=true
is set and the requester holds system.root — used by backup
tooling.
UTC time the user was created.
UTC time the user was last updated.
UTC time the user was archived. Archived users cannot sign in
(login fails with LoginUserArchived) and cannot be modified.
UTC time of the user's most recent activity.
A password in the payload does not meet the configured complexity
rules. Re-send with confirm=ignore_password_requirements to save
the user anyway.
The request could not be processed. The code field of the
response identifies the specific reason.
No authenticated user. The request must carry a valid access token.
The authenticated user is not allowed to perform the operation. The exact condition depends on the operation:
GET /user: only wheninclude_password=trueand the requester lackssystem.root— codeSystemRightRequired.GET /user/{id}: wheninclude_password=trueand the requester lackssystem.root(SystemRightRequired); or when a non-system.rootrequester neither owns the target user nor holds the per-userreadACL right — codeRightRequired.POST/PUT /user: when a non-system.rootrequester lacks the ACL right needed to create or modify a targeted user (linking/unlinking groups, writing another user, or changing an owner) — codeRightRequired. Other save-right violations (for example modifying a protected field of your own record) are reported as400, not403.DELETE /user/{id}: when the requester holds neithersystem.usernorsystem.root(SystemRightRequired); or when asystem.user-but-not-system.rootrequester lacks the per-userdeleteACL right on the target — codeRightRequired.POST /user/change_password: when the requester lacks thesystem.user.change_passwordsystem right (orsystem.root) — codeSystemRightRequired; or when the new password fails the configured complexity rules — codePasswordRequirementNotFulfilled(theerrormessage carries the configured password hint).
The user could not be saved because another user already has the same email or login.
PUT /user — Create or update one or more users (alias for POST).
PUT /user — Create or update one or more users (alias for POST).Access token in the Authorization header:
Authorization: Bearer <token>.
Set to ignore_password_requirements to re-submit a request that
was answered with a 202 because a password did not satisfy the
configured complexity rules, saving the user anyway (see the 202
response).
If true, skip email-format validation on the saved users.
Allowed only with system.root; without it the request fails
with a 400 (code ServerGeneric).
A user record. Used as the request and response body of the
/api/v1/user* endpoints.
Fixed marker identifying this object as a user.
Plaintext password (write-only). Set on user creation to seed a
password; otherwise use POST /user/change_password. Never echoed
back in responses.
The stored password hash. Only returned when include_password=true
is set and the requester holds system.root — used by backup
tooling.
UTC time the user was created.
UTC time the user was last updated.
UTC time the user was archived. Archived users cannot sign in
(login fails with LoginUserArchived) and cannot be modified.
UTC time of the user's most recent activity.
The users were saved.
A user record. Used as the request and response body of the
/api/v1/user* endpoints.
Fixed marker identifying this object as a user.
Plaintext password (write-only). Set on user creation to seed a
password; otherwise use POST /user/change_password. Never echoed
back in responses.
The stored password hash. Only returned when include_password=true
is set and the requester holds system.root — used by backup
tooling.
UTC time the user was created.
UTC time the user was last updated.
UTC time the user was archived. Archived users cannot sign in
(login fails with LoginUserArchived) and cannot be modified.
UTC time of the user's most recent activity.
A password in the payload does not meet the configured complexity
rules. Re-send with confirm=ignore_password_requirements to save
the user anyway.
The request could not be processed. The code field of the
response identifies the specific reason.
No authenticated user. The request must carry a valid access token.
The authenticated user is not allowed to perform the operation. The exact condition depends on the operation:
GET /user: only wheninclude_password=trueand the requester lackssystem.root— codeSystemRightRequired.GET /user/{id}: wheninclude_password=trueand the requester lackssystem.root(SystemRightRequired); or when a non-system.rootrequester neither owns the target user nor holds the per-userreadACL right — codeRightRequired.POST/PUT /user: when a non-system.rootrequester lacks the ACL right needed to create or modify a targeted user (linking/unlinking groups, writing another user, or changing an owner) — codeRightRequired. Other save-right violations (for example modifying a protected field of your own record) are reported as400, not403.DELETE /user/{id}: when the requester holds neithersystem.usernorsystem.root(SystemRightRequired); or when asystem.user-but-not-system.rootrequester lacks the per-userdeleteACL right on the target — codeRightRequired.POST /user/change_password: when the requester lacks thesystem.user.change_passwordsystem right (orsystem.root) — codeSystemRightRequired; or when the new password fails the configured complexity rules — codePasswordRequirementNotFulfilled(theerrormessage carries the configured password hint).
The user could not be saved because another user already has the same email or login.
GET /user/session — Information about the current session.
GET /user/session — Information about the current session.Returns the access token, the authenticated user, their groups,
system rights, the resolved configuration (defaults and base config)
and the instance settings. Does not require any specific system right
beyond being authenticated. Unlike the other /user operations, an
unauthenticated request is rejected with 400 InvalidToken rather
than 401.
Access token in the Authorization header:
Authorization: Bearer <token>.
The current session.
A session descriptor — returned by GET /api/v1/user/session.
Carries the access token, the authenticated user and their groups,
the system rights they hold, available authentication methods, and
instance-wide defaults the front end needs to render correctly.
The session's access token. Use it as the Bearer token (or in
the x-fylr-authorization / Authorization header) for
subsequent requests.
The user's preferred UI language as a BCP-47 tag (de-DE,
en-US, ...).
The latest _id issued in the event log when the session was
built. Pass it as fromEventId to /api/v1/event/poll/{fromEventId}
to subscribe to subsequent events.
No authenticated user — the request carried no token or an
invalid one. The code is InvalidToken.
POST /user/change_password — Change the authenticated user's password.
POST /user/change_password — Change the authenticated user's password.Changes the authenticated user's password. The current password
(password) must be supplied and is verified; it is always the
authenticated user's own password that is changed. Requires the
system.user.change_password system right (or system.root). The new
password must satisfy the configured complexity rules. On success, the
user's existing OAuth2 tokens are invalidated.
The request body is form-encoded (application/x-www-form-urlencoded)
or sent as a JSON object; the fields below are read with FormValue.
Access token in the Authorization header:
Authorization: Bearer <token>.
The new password.
The current password, re-confirmed. Must be non-empty and must match the authenticated user's current password.
Password was changed.
The request could not be processed. The code field of the
response identifies the specific reason.
No authenticated user. The request must carry a valid access token.
The authenticated user is not allowed to perform the operation. The exact condition depends on the operation:
GET /user: only wheninclude_password=trueand the requester lackssystem.root— codeSystemRightRequired.GET /user/{id}: wheninclude_password=trueand the requester lackssystem.root(SystemRightRequired); or when a non-system.rootrequester neither owns the target user nor holds the per-userreadACL right — codeRightRequired.POST/PUT /user: when a non-system.rootrequester lacks the ACL right needed to create or modify a targeted user (linking/unlinking groups, writing another user, or changing an owner) — codeRightRequired. Other save-right violations (for example modifying a protected field of your own record) are reported as400, not403.DELETE /user/{id}: when the requester holds neithersystem.usernorsystem.root(SystemRightRequired); or when asystem.user-but-not-system.rootrequester lacks the per-userdeleteACL right on the target — codeRightRequired.POST /user/change_password: when the requester lacks thesystem.user.change_passwordsystem right (orsystem.root) — codeSystemRightRequired; or when the new password fails the configured complexity rules — codePasswordRequirementNotFulfilled(theerrormessage carries the configured password hint).
GET /user/{id} — Retrieve a single user by id.
GET /user/{id} — Retrieve a single user by id.Access token in the Authorization header:
Authorization: Bearer <token>.
The user's _id.
If true, the response includes the stored password hash (for
backup tooling). Requires system.root.
The user, returned as an array with a single element. When the id
is well-formed but no user exists, the response is 400 with code
UserNotFound (not 404).
A user record. Used as the request and response body of the
/api/v1/user* endpoints.
Fixed marker identifying this object as a user.
Plaintext password (write-only). Set on user creation to seed a
password; otherwise use POST /user/change_password. Never echoed
back in responses.
The stored password hash. Only returned when include_password=true
is set and the requester holds system.root — used by backup
tooling.
UTC time the user was created.
UTC time the user was last updated.
UTC time the user was archived. Archived users cannot sign in
(login fails with LoginUserArchived) and cannot be modified.
UTC time of the user's most recent activity.
The request could not be processed. The code field of the
response identifies the specific reason.
No authenticated user. The request must carry a valid access token.
The authenticated user is not allowed to perform the operation. The exact condition depends on the operation:
GET /user: only wheninclude_password=trueand the requester lackssystem.root— codeSystemRightRequired.GET /user/{id}: wheninclude_password=trueand the requester lackssystem.root(SystemRightRequired); or when a non-system.rootrequester neither owns the target user nor holds the per-userreadACL right — codeRightRequired.POST/PUT /user: when a non-system.rootrequester lacks the ACL right needed to create or modify a targeted user (linking/unlinking groups, writing another user, or changing an owner) — codeRightRequired. Other save-right violations (for example modifying a protected field of your own record) are reported as400, not403.DELETE /user/{id}: when the requester holds neithersystem.usernorsystem.root(SystemRightRequired); or when asystem.user-but-not-system.rootrequester lacks the per-userdeleteACL right on the target — codeRightRequired.POST /user/change_password: when the requester lacks thesystem.user.change_passwordsystem right (orsystem.root) — codeSystemRightRequired; or when the new password fails the configured complexity rules — codePasswordRequirementNotFulfilled(theerrormessage carries the configured password hint).
DELETE /user/{id} — Delete a user by id.
DELETE /user/{id} — Delete a user by id.Removes a user. System users (system:root, system:everybody, ...)
cannot be deleted, and the requester cannot delete themselves. The
behaviour is selected by delete_policy:
delete— hard-deletes the user record. Objects, pools, groups and share links owned by the user are reassigned to the system usersystem:deleted_user. Irreversible.archive— sets_archived_atand pseudonymizes the user record (name, address, login and email are cleared or randomized per the group's pseudonymization configuration). The user's collections are deleted and cannot be restored. Irreversible.unarchive— restores a previously archived user.
When delete_policy is omitted, the instance's configured default
policy applies; if that is ask (or the selection is ambiguous), the
endpoint returns a 202 prompting the caller to choose (see below).
The deleted, archived or restored user record(s) are returned.
Differs from easydb 5: the caller chooses the outcome explicitly via
delete_policy (delete, archive or unarchive), and an omitted
policy can yield a 202 prompt. In easydb 5 there is no such
parameter — the user "is archived if there has been activity,
otherwise deleted", and there is no unarchive via this endpoint.
Access token in the Authorization header:
Authorization: Bearer <token>.
The user's _id.
How to remove the user. Omit to receive a 202 prompting for the
choice (when the configured default policy is ask). See the
operation description for the semantics of each value.
Carried by the 202 confirm button. The operative parameter when
resolving the 202 is delete_policy.
The affected user record(s), as an array of UserApi.
A user record. Used as the request and response body of the
/api/v1/user* endpoints.
Fixed marker identifying this object as a user.
Plaintext password (write-only). Set on user creation to seed a
password; otherwise use POST /user/change_password. Never echoed
back in responses.
The stored password hash. Only returned when include_password=true
is set and the requester holds system.root — used by backup
tooling.
UTC time the user was created.
UTC time the user was last updated.
UTC time the user was archived. Archived users cannot sign in
(login fails with LoginUserArchived) and cannot be modified.
UTC time of the user's most recent activity.
No delete_policy was supplied (and the default is ask). The body
lists the allowed policies; re-send with the chosen delete_policy.
The request could not be processed. The code field of the
response identifies the specific reason.
No authenticated user. The request must carry a valid access token.
The authenticated user is not allowed to perform the operation. The exact condition depends on the operation:
GET /user: only wheninclude_password=trueand the requester lackssystem.root— codeSystemRightRequired.GET /user/{id}: wheninclude_password=trueand the requester lackssystem.root(SystemRightRequired); or when a non-system.rootrequester neither owns the target user nor holds the per-userreadACL right — codeRightRequired.POST/PUT /user: when a non-system.rootrequester lacks the ACL right needed to create or modify a targeted user (linking/unlinking groups, writing another user, or changing an owner) — codeRightRequired. Other save-right violations (for example modifying a protected field of your own record) are reported as400, not403.DELETE /user/{id}: when the requester holds neithersystem.usernorsystem.root(SystemRightRequired); or when asystem.user-but-not-system.rootrequester lacks the per-userdeleteACL right on the target — codeRightRequired.POST /user/change_password: when the requester lacks thesystem.user.change_passwordsystem right (orsystem.root) — codeSystemRightRequired; or when the new password fails the configured complexity rules — codePasswordRequirementNotFulfilled(theerrormessage carries the configured password hint).
Last updated