Create user

ENDPOINT /api/v0-user/create/ (POST only)

The body of the request should be a JSON document containing the fields below:

Field Explanation
nameFirst Required. The user’s first name
nameLast Required. The user’s last name
email Required. The email address for the user. Must be unique.
ref Optional. The ref of the StoreObject representing this user
tags Optional. Any tags (such as username) that should be set for this user. These tags can be used to query users. If username is set, it must be unique.
localeId Optional. If unspecified, will use the application’s default locale.
directGroupMembership Optional. Array of group API codes specifying the direct group membership of this user.

An optional parameter of welcomeLink can be included. Passing a value of 1 will include a welcome link for the newly created user to set their password and log in to the system.

Membership of std:group:everyone is implied, and should not be specified in directGroupMembership.

Example request body

{
    "nameFirst":"First",
    "nameLast":"Last",
    "email":"first.last@example.com",
    "localeId":"en",
    "tags": {
        "username": "abc123",
        "flag": "other"
    },
    "directGroupMembership":[
        "std:group:administrators"
        "haplo:group:example"
    ]
}

Response

This request can respond with following kinds, in addition to the generic kinds (see Introduction):

Kind Meaning HTTP status
haplo:api-v0:user:create The request was successful and the new user’s details have been returned 200
haplo:api-v0:user:creation-failed A user could not be created the provided details. 400

Along with the standard success and kind fields (see Introduction for explanation), the response has the following structure:

  • welcomeLink (optional, see above)
  • user
    • id
    • nameFirst
    • nameLast
    • name
    • code
    • email
    • ref
    • isGroup
    • isActive
    • isSuperUser
    • isServiceUser
    • isAnonymous
    • localeId
    • tags
    • directGroupMembership

Apart from directGroupMembership, all the fields correspond directly to the equivalent field on the SecurityPrincipal. directGroupMembership is the equivalent of directGroupIds, but returns an array of group API codes instead of group IDs.

Example response

{
    "success": true,
    "kind": "haplo:api-v0:user:create",
    "welcomeLink": "https://app.example.org/do/authentication/welcome/130-abcdef1234567890",
    "user": {
        "id":130,
        "nameFirst":"First",
        "nameLast":"Last",
        "name":"First Last",
        "code":null,
        "email":"first.last@example.com",
        "ref":null,
        "isGroup":false,
        "isActive":true,
        "isSuperUser":false,
        "isServiceUser":false,
        "isAnonymous":false,
        "localeId":"en",
        "tags": {
            "username": "abc123",
            "flag": "other"
        },
        "directGroupMembership":[
            "std:group:administrators"
            "haplo:group:example"
        ]
    }
}