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

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/

Return users from the configured resolvers.

When called by a regular user the response is restricted to that user’s own record — the user / realm / resolver parameters are bound to the calling user before the search runs.

Requires admin authentication and the policy action userlist to list other users.

Realm and resolver scoping is additive: realm=R queries every resolver in R, resolver=X queries X, and combining both queries the union. With neither parameter all resolvers across all realms are queried.

Query Parameters:

  • realm – query every resolver in this realm.

  • resolver – query this resolver.

  • username (user /) – filter by login name; supports the * wildcard.

  • <resolver-attr> – any other key is forwarded to each resolver’s getUserList as a search field. Wildcard support is resolver-class-specific.

  • attributes – comma-separated list of attribute names to return per user. In addition to user-store attributes, resolver and editable are privacyIDEA-managed extras. If omitted, all attributes are returned.

  • include_custom_attributes – True (default) merges privacyIDEA custom user attributes into the response. Custom attributes are only merged when a single realm is in scope.

Status Codes:

  • 200 OK – list of user dictionaries in result.value.

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,...",
        "resolver": "ldap-corp"
      }
    ]
  },
  "version": "privacyIDEA unknown"
}
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). Attribute keys starting with an internal privacyIDEA prefix are rejected.

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.

  • 400 Bad Request – attribute name uses a reserved internal prefix.

  • 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/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=...