1.55 Users

This section covers the user resource methods.

/api/26/users

1.55.1 User query

The users resource offers additional query parameters beyond the standard parameters (e.g. paging). To query for users at the users resource you can use the following parameters.

User query parameters
Parameter Type Description
query Text Query value for first name, surname, username and email, case in-sensitive.
phoneNumber Text Query for phone number.
canManage false | true Filter on whether the current user can manage the returned users through the managed user group relationships.
authSubset false | true Filter on whether the returned users have a subset of the authorities of the current user.
lastLogin Date Filter on users who have logged in later than the given date.
inactiveMonths Number Filter on users who have not logged in for the given number of months.
inactiveSince Date Filter on users who have not logged in later than the given date.
selfRegistered false | true Filter on users who have self-registered their user account.
invitationStatus none | all | expired Filter on user invitations, including all or expired invitations.
ou Identifier Filter on users who are associated with the organisation unit with the given identifier.
includeChildren false | true Includes users from all children organisation units of the ou parameter.
page Number The page number.
pageSize Number The page size.

A query for max 10 users with “konan” as first name or surname (case in-sensitive) who have a subset of authorities compared to the current user:

/api/26/users?query=konan&authSubset=true&pageSize=10

1.55.2 User credentials query

An alternative to the previous user query, is to directly query the user credentials (the part where username, etc., resides) using /api/userCredentials endpoint, it supports all regular field and object filters as the other endpoints.

Get user credentials where username is admin:

/api/26/userCredentials?filter=username:eq:admin

Get username and code from all user credentials where username starts with adm :

/api/26/userCredentials?fields=username,code&filter=username:^like:adm

1.55.3 User account create and update

Both creating and updating a user is supported through the web-api. The payload itself is similar to other payloads in the web-api, so they support collection references etc. A simple example payload to create would be, the password should be sent in plain text (remember to only use this on a SSL enabled server) and will be encrypted on the backend:

{
  "id": "Mj8balLULKp",
  "firstName": "John",
  "surname": "Doe",
  "email": "johndoe@mail.com",
  "userCredentials": {
    "id": "lWCkJ4etppc",
    "userInfo": {
      "id": "Mj8balLULKp"
    },
    "username": "johndoe123",
    "password": "Your-password-123",
    "userRoles": [
      {
        "id": "Ufph3mGRmMo"
      }
    ]
  },
  "organisationUnits": [
    {
      "id": "Rp268JB6Ne4"
    }
  ],
  "userGroups": [
    {
      "id": "wl5cDMuUhmF"
    }
  ]
}

curl -X POST -u user:pass -d @u.json -H "Content-Type: application/json" http://server/api/26/users

After the user is created, a Location header is sent back with the newly generated ID (you can also provide your own using /api/system/id endpoint). The same payload can then be used to do updates, but remember to then use PUT instead of POST and the endpoint is now /api/users/ID .

curl -X PUT -u user:pass -d @u.json -H "Content-Type: application/json" http://server/api/26/users/ID

For more info about the full payload available, please see /api/schemas/user

1.55.4 User account invitations

The Web API supports inviting people to create user accounts through the invite resource. To create an invitation you should POST a user in XML or JSON format to the invite resource. A specific username can be forced by defining the username in the posted entity. By omitting the username, the person will be able to specify it herself. The system will send out an invitation through email. This requires that email settings have been properly configured. The invite resource is useful in order to securely allow people to create accounts without anyone else knowing the password or by transferring the password in plain text. The payload to use for the invite is the same as for creating users. An example payload in JSON looks like this:

{
  "firstName": "John",
  "surname": "Doe",
  "email": "johndoe@mail.com",
  "userCredentials": {
    "username": "johndoe",
    "userRoles": [ {
      "id": "Euq3XfEIEbx"
    } ]
  },
  "organisationUnits": [ {
    "id": "ImspTQPwCqd"
  } ],
  "userGroups": [ {
    "id": "vAvEltyXGbD"
  } ]
}

The user invite entity can be posted like this:

curl -d @invite.json "localhost/api/26/users/invite" -H "Content-Type:application/json" -u admin:district -v

To send out invites for multiple users at the same time you must use a slightly different format. For JSON:

{
  "users": [ {
    "firstName": "John",
    "surname": "Doe",
    "email": "johndoe@mail.com",
    "userCredentials": {
      "username": "johndoe",
      "userRoles": [ {
        "id": "Euq3XfEIEbx"
      } ]
    },
    "organisationUnits": [ {
      "id": "ImspTQPwCqd"
      } ]
    }, {
    "firstName": "Tom",
    "surname": "Johnson",
    "email": "tomj@mail.com",
    "userCredentials": {
      "userRoles": [ {
        "id": "Euq3XfEIEbx"
      } ]
    },
    "organisationUnits": [ {
      "id": "ImspTQPwCqd"
      } ]
    }
  ]
}

To create multiple invites you can post the payload to the api/users/invites resource like this:

curl -d @invites.json "localhost/api/26/users/invites" -H "Content-Type:application/json"
  -u admin:district

There are certain requirements for user account invitations to be sent out:

  • Email SMTP server must be configured properly on the server.

  • The user to be invited must have specified a valid email.

  • The user to be invited must not be granted user roles with critical authorities (see below).

  • If username is specified it must not be already taken by another existing user.

If any of these requirements are not met the invite resource will return with a 409 Conflict status code together with a descriptive message.

The critical authorities which cannot be granted with invites include:

  • ALL

  • Scheduling administration

  • Set system settings

  • Add, update, delete and list user roles

  • Add, update, delete and view SQL views

1.55.5 User replication

To replicate a user you can use the replica resource. Replicating a user can be useful when debugging or reproducing issues reported by a particular user. You need to provide a new username and password for the replicated user which you will use to authenticate later. Note that you need the ALL authority to perform this action. To replicate a user you can post a JSON payload looking like below:

{
  "username": "replica",
  "password": "Replica.1234"
}

This payload can be posted to the replica resource, where you provide the identifier of the user to replicate in the URL:

/api/26/users/<uid>/replica

An example of replicating a user using curl looks like this:

curl -d @replica.json "localhost/api/26/users/N3PZBUlN8vq/replica"
  -H "Content-Type:application/json" -u admin:district -v