16.1.1.12. User endpoints¶

The user endpoints is a subset of the system endpoint.

GET /user/¶

list the users in a realm

A normal user can call this endpoint and will get information about his own account.

Query Parameters:

realm – a realm that contains several resolvers. Only show users from this realm
resolver – a distinct resolvername
<searchexpr> – a search expression, that depends on the ResolverClass

Return:

json result with “result”: true and the userlist in “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": [
       {
         "description": "Cornelius Kölbel,,+49 151 2960 1417,+49 561 3166797,cornelius.koelbel@netknights.it",
         "email": "cornelius.koelbel@netknights.it",
         "givenname": "Cornelius",
         "mobile": "+49 151 2960 1417",
         "phone": "+49 561 3166797",
         "surname": "Kölbel",
         "userid": "1009",
         "username": "cornelius",
         "resolver": "name-of-resolver"
       }
     ]
   },
   "version": "privacyIDEA unknown"
 }

POST /user/attribute¶

Set a custom attribute for a user. The user is specified by the usual parameters user, resolver and realm. When a user is calling the endpoint the parameters will be implicitly set.

JSON Parameters:

user – The username of the user, for whom the attribute should be set
resolver – The resolver of the user (optional)
realm – The realm of the user (optional)
key – The name of the attributes
value – The value of the attribute
type – an optional type of the attribute

The database id of the attribute is returned. The return value thus should be >=0.

GET /user/attribute¶

Return the custom attribute of the given user. This does not return the user attributes which are contained in the user store! The user is specified by the usual parameters user, resolver and realm. When a user is calling the endpoint the parameters will be implicitly set.

Query Parameters:

user – The username of the user, for whom the attribute should be set
resolver – The resolver of the user (optional)
realm – The realm of the user (optional)
key – The optional name of the attribute. If it is not specified all custom attributes of the user are returned.

GET /user/editable_attributes/¶

The resulting editable custom attributes according to the policies are returned. This can be a user specific result. When a user is calling the endpoint the parameters will be implicitly set.

Query Parameters:

user – The username of the user, for whom the attribute should be set
resolver – The resolver of the user (optional)
realm – The realm of the user (optional)

Works for admins and normal users. :return:

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

Delete a specified custom attribute from the user. The user is specified by the positional parameters user and realm.

Parameters:

username – The username of the user, for whom the attribute should be set
realm – The realm of the user
attrkey – The name of the attribute that should be deleted from the user.

Returns the number of deleted attributes.

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

Delete a User in the user store. The resolver must have the flag editable, so that the user can be deleted. Only administrators are allowed to delete users.

Parameters:

resolvername – The name of the resolver
username – The username of the user, who should be deleted

Delete a user object in a user store by calling

Example request:

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

POST /user/¶

POST /user¶

Create a new user in the given resolver.

Example request:

POST /user HTTP/1.1
Host: example.com
Accept: application/json

user=new_user
resolver=<resolvername>
surname=...
givenname=...
email=...
mobile=...
phone=...
password=...
description=...

PUT /user/¶

PUT /user¶

Edit a user in the user store. The resolver must have the flag editable, so that the user can be deleted. Only administrators are allowed to edit users.

Example request:

PUT /user HTTP/1.1
Host: example.com
Accept: application/json

user=existing_user
resolver=<resolvername>
surname=...
givenname=...
email=...
mobile=...
phone=...
password=...
description=...

Note

Also a user can call this function to e.g. change his password. But in this case the parameter “user” and “resolver” get overwritten by the values of the authenticated user, even if he specifies another username.