Retrieve users

GET /api/v1/user[/<id>]?token=<token>[&limit=<limit>][&offset=<offset>][&groupids=<groupids>][&type=<type>][&changed_since=<changed_since>][&include_password=<include_password>]

Retrieves one user or a list of users, ordered by the user ID (ascending).

Path parameters

Query String

Returns

Array of users. The field password will not be returned. But you can retrieve the password hashes and crypt methods explicitly (see “Returning password hashes”).

Depending on the rights of the user, some fields may not be visible. See “Permissions”.

Permissions

The session must be authenticated.

The session user requires the system.user right and read for the user.

Additionally, a user can read some information about itself (session user is the same as requested user), even if it does not have the write right:

• all "short" format fields
• frontend_prefs
• any fields that are checked in the system.user.write_self

Returning password hashes

This should only be used for migrations, and is protected by multiple settings and rights. Since this might pose a security risk, it should be avoided!

By requesting the users with &include_password=true, the user records will include the password hash and crypt method (see Full format)

Necessary rights and server settings are:

• The session needs to system.root right
  • if the session has no root right, a No System Right error is caused
• The server config variable server.api.user.include_password must be set to true to enable this API call (see easydb-server.yml)
  • if this setting is missing, this request will not cause an error, but a warning will be logged and the user records are returned without any passsword hashes

The known values for _password_insecure_hash_method are:

• md5: The returned _password_insecure_hash is a hexadecimal MD5 checksum. It’s a direct hash of the password without a salt value.
• sha-512: The returned _password_insecure_hash is a SHA 512 hash value as used in the sha512crypt method. Its length is 86 characters from the set ./0-9A-Za-z. In addition _password_insecure_hash_salt is returned containing the salt used for the hashing. Its length is 16 characters.

HTTP status codes

Examples

Request:  GET /api/v1/user/2
Response: HTTP 200
[
    {
        "user": {
            "_id": 2,
            "_version": 3,
            "is_system_user": false,
            "login": "jsmith",
            "first_name": "John",
            "last_name": "Smith",
            "displayname": "Dr. John Smith",
            "frontend_prefs": {
                "frontend-skin": "aqua"
            }
        },
        ...
    }
]

Insert or update users

POST/PUT /api/v1/user?token=<token>

Creates (PUT) or updates (POST) users. The related “user collection” will be created or updated (if required).

Query String

Input

Array of users. Depending on the user rights, more or less information is available: see GET above.

Ouput

Array of users that were updated.

New primary e-mail

If the request includes a _new_primary_email it will be processed as follows:

• if the e-mail address exists
  • if it is already primary, an error is returned
  • if it is not primary but it is not confirmed, mark it as intended primary and resend the confirmation e-mail
  • if it is not primary and it is confirmed, it will become primary
• if the e-mail address does not exist, create it and mark it to become primary when it is confirmed
  • if there is already a pending confirmation for a different address, delete it

The e-mail address remains as _new_primary_email until it is confirmed.

Email sending

Inserting or updating users might trigger sending of emails to one or more of the user’s email addresses. Each email contains different parts:

For the email part and the password part there is at most one part each, it may also be missing completely. If neither an email part or a password part is given, no email is sent at all.

When sent_email of the email address is not set to true, no email is sent to this address, either.

email part

The first part which meets all conditions is used:

cancel a requested confirmation of an email address

When a confirmation request has been sent, the confirmation request can be cancelled by sending the write-only parameter "cancel_confirmation": true.

This also overrules the write-only parameter needs_confirmation.

password part

The first part which meets all conditions is used:

Permissions

The session must be authenticated.

Updating a user

If the session user has the write right for the user, the user is editable.

In the case that the user groups are provided (_groups), notice that:

• if a group is added, the user requires the link right for the group
• if a group is deleted, the user requires the unlink right for the group
• system groups cannot be added or deleted, they are automatically set for the session

Additionally, a user can edit some information about itself (session user is the same as requested user), even if it does not have the write right:

• frontend_prefs
• language
• any fields that are checked in the system.user.write_self

If the user is a system user (type “system”), the following parameters cannot be modified:

• login
• _acl
• _system_rights.
• _groups.

Any attempt to modify one of them will result in a User Update System Group error.

A user cannot disable its own login (i.e. set login_disabled to true).

Creating a user

If a user is created, the session user requires the system.user right with create. This right implies the write right and the rules for update apply. This means, for example, that if the user is linked to a group, the link right for the group must exist for the user.

When creating a user, the owner will be set to the session user. An attempt to set a different owner will trigger a Change Owner On Creation error.

HTTP status codes

Examples

Request:  PUT /api/v1/user
[
    {
        "user": {
            "_version": 1,
            "login": "sysadmin",
            "_include_password_in_email": true
        }
        "_groups": [
            5
        ],
        "_emails": [
            {
                "email": "sysadmin@organization.com"
            }
        ],
        "_owner": { … },
	    "_password": null || "string" || true // with true a password will be generated

    }
]
Response: HTTP 200
[
    {
        "user": {
            "_id": 13,                      // ID is returned in the response
            "_version": 1,
            "login": "sysadmin",
            "displayname": "sysadmin@organization.com"
        },
        "_groups": [
            5
        ],
        "_emails": [
            {
                "email": "sysadmin@organization.com",
            }
        ],
        "_owner": { … }
    }
]

Request:  POST /api/v1/user
[
    {
        "user": {
            "_id": 13,
            "_version": 2,
            "displayname": "System Admin"
        },
        "_owner": { … }
    }
]
Response: HTTP 200
[
    {
        "user": {
            "_id": 13,
            "_version": 2,
            "login": "sysadmin",
            "displayname": "System Admin"
        },
        "_groups": [
            5
        ],
        "_emails": [
            {
                "email": "sysadmin@organization.com",
            }
        ],
        "_owner": { … }
    }
]

Delete user

DELETE /api/v1/user/<id>?token=<token>

Delete a user. The user is archived if there has been activity, otherwise deleted.

The user collection is also deleted, along with its subtree.

Path parameters

Query String

Permissions

The session must be authenticated and have the delete right for the user provided.

System users are not allowed to be deleted.

HTTP status codes

Examples

Request:  DELETE /api/v1/user/2
Response: HTTP 200