The user REST API exposes the user records held by the configured user resolvers (LDAP, SQL, …). Endpoints fall in three groups:

listing / lookup — GET /user/.
user-store CRUD against editable resolvers — admin-only: POST /user/, PUT /user/, DELETE /user/(resolvername)/(username).
custom user attributes — small key/value records that privacyIDEA attaches to a user independent of the user store: GET /user/attribute, POST /user/attribute, DELETE /user/attribute/(attrkey)/(username)/(realm), GET /user/editable_attributes/.

CRUD on user-store records requires admin authentication and the respective policy action (adduser, updateuser, deleteuser); the underlying resolver must also have the editable flag set. Listing is gated by userlist and is realm-scoped for realm-admins. The custom-attribute write/delete endpoints are gated by the set_custom_user_attributes and delete_custom_user_attributes policies and may be invoked by users on themselves as well as by admins on other users.

16.1.1.12. User endpoints¶

The user endpoints is a subset of the system endpoint.

GET /user/¶

List users from the configured resolvers.

Who may call this

Both administrators and regular users may call this endpoint. Requires the policy action userlist in the matching scope (admin scope for admins, user scope for users). For non-admin callers the user / realm / resolver parameters are overwritten with the caller’s own identity before the search runs, so a regular user only ever sees their own record.

Realm and resolver scoping

realm=R only — queries every resolver assigned to realm R. Several realms may be given as a comma-separated list.
resolver=X only — queries only resolver X, in every realm that contains it.
realm=R together with resolver=X — queries only X within R. The result is empty if X is not part of R.
Neither parameter — queries every resolver in every realm.

If an admin caller omits realm= and their matching userlist policy grants one or more realms, every realm granted across their matching policies is used (the union), unless any matching policy grants no realms at all, in which case no realm filter is added and every realm is queried.

Query Parameters:

realm – realm to list (see scoping rules above).
resolver – resolver to list (see scoping rules above).
username (user /) – filter by login name. Both keys are accepted; user wins if both are sent. Wildcard support (e.g. *) is resolver-class-specific.
<resolver-attr> – any other key is forwarded to each resolver’s getUserList as an additional search field. Wildcard support is resolver-class-specific. A resolver that rejects an unknown search key is skipped for that request and reported back via detail.skipped_resolvers (see :status:`200`); this applies to the SQL, LDAP and passwd resolvers. HTTP-based resolvers (e.g. Keycloak, Entra ID) instead silently drop an unrecognised key and search without it, so an unmapped attribute is never reported as skipped there. The SCIM resolver does not apply any of the given search fields at all.
attributes – comma-separated list of attribute names to return per user (whitespace around names is stripped). In addition to user-store attributes, the privacyIDEA-managed extras realm, resolver and editable may be requested. Names the resolver does not recognise are silently dropped from the response. When omitted, the response contains every user-store attribute plus the three privacyIDEA extras.
include_custom_attributes – defaults to True and merges privacyIDEA custom user attributes into each user record. The default is forced to False if no custom attributes are defined anywhere in the database, to skip an unnecessary per-user lookup.

Status Codes:

200 OK – list of user dictionaries in result.value. If any targeted resolver raised an error (broken connection, unknown search key, …) the request still returns 200 with the partial result; the names of the skipped resolvers are reported in detail.skipped_resolvers.

Example request:

GET /user/?realm=realm1 HTTP/1.1
Host: example.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "status": true,
    "value": [
      {
        "username": "alice",
        "userid": "1009",
        "givenname": "Alice",
        "surname": "Liddell",
        "email": "alice@example.com",
        "mobile": "+44 12345",
        "phone": "+44 67890",
        "description": "Alice Liddell,...",
        "realm": "realm1",
        "resolver": "ldap-corp",
        "editable": false
      }
    ]
  },
  "version": "privacyIDEA unknown"
}

GET /user/settings¶

Return the WebUI settings of the logged-in principal.

The settings are always scoped to the caller’s own JWT identity; there is no way to read another principal’s settings through this endpoint. The stored document is returned verbatim (an empty object if nothing has been stored); the WebUI applies its own defaults for absent keys.

Requires authentication (any role).

Request Headers:

PI-Authorization – JWT auth token returned by POST /auth.

Status Codes:

200 OK – the settings object in result.value.

POST /user/settings¶

Store WebUI settings for the logged-in principal.

By default the given keys are merged into the existing settings; pass replace=1 to replace the whole document. The values are stored as given and are not validated. Always scoped to the caller’s own JWT identity.

Requires authentication (any role).

JSON Parameters:

settings – a JSON object with the settings to store.
replace – if true, replace the whole document instead of merging.

Status Codes:

200 OK – the stored settings object in result.value – the same shape GET /user/settings returns.
400 Bad Request – the settings are not a JSON object, contain a key that is not known (see PI_USER_SETTINGS_ALLOWED_KEYS), are not JSON-serializable, or exceed the maximum size.

DELETE /user/settings/(key)¶

DELETE /user/settings¶

Delete WebUI settings of the logged-in principal.

With a key path segment only that setting is removed (the WebUI then falls back to its own default for it); without one the whole document is cleared. Always scoped to the caller’s own JWT identity.

Requires authentication (any role).

Parameters:

key – the single setting to delete; omit to clear all settings.

Status Codes:

200 OK – the remaining settings object in result.value.

POST /user/attribute¶

Set a custom user attribute. Custom attributes are key/value records privacyIDEA stores alongside a user, independent of the user store.

When invoked by a regular user the user / resolver / realm body fields are bound to the calling user.

Authorization is gated by the set_custom_user_attributes policy. The policy value whitelists allowed key/value combinations (the * wildcard is allowed for keys or values).

JSON Parameters:

user – user name (required).
resolver – resolver name.
realm – realm name.
key – attribute name (required).
value – attribute value (required).
type – optional attribute type identifier.

Status Codes:

200 OK – database id of the attribute row in result.value.
403 Forbidden – the active policy does not allow this key/value combination.

GET /user/attribute¶

Return custom user attributes. This does not include attributes from the user store (those come back via GET /user/); only the privacyIDEA-managed custom attributes are returned.

When invoked by a regular user the user / resolver / realm parameters are bound to the calling user.

Query Parameters:

user – user name (required to identify the target).
resolver – resolver name.
realm – realm name.
key – attribute name. If omitted, all custom attributes are returned as a dict; if given, the value of that single attribute is returned (or null if it is not set).

Status Codes:

200 OK – attribute value or dict of attributes in result.value.

GET /user/internal_attribute¶

Return privacyIDEA-internal attributes for a user. These are caches privacyIDEA writes about itself (e.g. fido2_user_id, last_used_token) and are NOT user-facing — admin-only, read-only.

Requires the policy action policy_get_user_internal_attributes. A realm-restricted admin is confined to their realms.

Intended for support / debugging via the WebUI details panel.

Query Parameters:

user – user name (required).
resolver – resolver name.
realm – realm name.

Status Codes:

200 OK – dict of internal attributes in result.value.

GET /user/editable_attributes/¶

Return the custom user attributes that the calling principal is allowed to set or delete on the given user, computed from the active set_custom_user_attributes and delete_custom_user_attributes policies. The WebUI uses this to decide which fields to render as editable.

When invoked by a regular user the user / resolver / realm parameters are bound to the calling user.

The result is a dict with two keys:

"delete" — list of attribute names that may be deleted; * means any attribute name.
"set" — dict of key: [allowed_values]; * may appear as a key (any key allowed) or in the value list (any value allowed).

Query Parameters:

user – user name (required to identify the target).
resolver – resolver name.
realm – realm name.

Status Codes:

200 OK – editable-attributes dict in result.value.

DELETE /user/attribute/(attrkey)/(username)/(realm)¶

Delete a single custom user attribute from the named user.

Authorization is gated by the delete_custom_user_attributes policy: a whitespace-separated list of allowed attribute names; * matches any name.

Parameters:

attrkey – path component, the attribute name to remove.
username – path component, the target user.
realm – path component, the target realm.

Status Codes:

200 OK – number of attribute rows removed in result.value.
403 Forbidden – the active policy does not allow deleting this attribute name, or a non-admin caller targeted a different user.

DELETE /user/(resolvername)/(username)¶

Delete a user from the user store. The resolver must have the editable flag set.

Requires admin authentication and the policy action deleteuser.

Parameters:

resolvername – path component, the resolver the user lives in.
username – path component, the user name to delete.

Status Codes:

200 OK – True on success in result.value.

Example request:

DELETE /user/<resolvername>/<username> HTTP/1.1
Host: example.com
Accept: application/json

POST /user/¶

POST /user¶

Create a new user in an editable resolver. The set of fields read from the request is determined by the resolver’s attribute map — fields outside that map are ignored.

Requires admin authentication and the policy action adduser.

JSON Parameters:

user – user name of the new user (required).
resolver – resolver to create the user in (required).
password – password the user will authenticate with.

Jsonparam:

any other attribute name in the resolver’s map (surname, givenname, email, mobile, phone, description, …).

Status Codes:

200 OK – id of the new user in result.value.

Example request:

POST /user/ HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

user=new_user&resolver=local-sql&surname=Doe&givenname=Jane
&email=jane@example.com&password=...

PUT /user/¶

PUT /user¶

Update a user in an editable resolver.

Admins may update any user the updateuser policy permits. An authenticated user without admin role may update only themselves — the user / resolver / realm body fields are bound to the calling user (typical use: a user changing their own password).

Requires the policy action updateuser. The resolver must have the editable flag set.

JSON Parameters:

user – user name (required).
resolver – resolver name (required).
userid – optional user id; if given, identifies the record by uid instead of by login.
password – new password (sent through password= rather than as an attribute field).

Jsonparam:

any other attribute name in the resolver’s map.

Status Codes:

200 OK – True on success in result.value.

Example request:

PUT /user/ HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

user=existing_user&resolver=local-sql&password=...&email=...