Creating and updating users

Creating users

To create a user, use the following endpoint:

  • POST /admin/v1/users
Note: When a user is created through Cloud API, the user's password is set to a value that cannot be used for authentication. (The password is set to a value that is not a valid Base64 string, but the authentication framework can authenticate passwords only when they are valid Base64 strings.) In order for the new user to authenticate, the password must first be changed to a valid Base64 string through some other method, such as through the user interface.

Create a minimal user

The minimum creation criteria for a user is the username. For example, the following request creates a user with the user name "amartin".

{
  "data": {
    "attributes": {
      "username": "amartin"
    }
  }
}

The following is the response payload.

POST /admin/v1/users

{
    "data": {
        "attributes": {
            "active": true,
            "displayName": "",
            "externalUser": false,
            "id": "pc:SatEdbNuwVSfc2BvbG4g4",
            "organization": {
                "displayName": "Enigma Fire & Casualty",
                "id": "systemTables:1",
                "type": "Organization",
                "uri": "/admin/v1/organizations/systemTables:1"
            },
            "useOrgAddress": true,
            "useProducerCodeSecurity": false,
            "userType": {
                "code": "other",
                "name": "Other"
            },
            "username": "amartin",
            "vacationStatus": {
                "code": "atwork",
                "name": "At work"
            }
        },
        "checksum": "8b01f84c8076ba3f8c235cb2483cdbfb",
        "links": {
            "self": {
                "href": "/admin/v1/users/pc:SatEdbNuwVSfc2BvbG4g4",
                "methods": [
                    "get",
                    "patch"
                ]
            }
        }
    }
}

Create a typical user

You can specify additional information about a user as specified in the User schema. For example, the following payload creates a user with the following attributes:

  • First name: Adriana
  • Last name: Diaz
  • User name: adiaz
  • Employee number: ACME-02027
  • Roles: audit examiner (audit_examiner) and audit supervisor (audit_supervisor)
POST /admin/v1/users

{
  "data": {
    "attributes": {
        "firstName": "Adriana",
        "lastName": "Diaz",
        "username": "adiaz",
        "employeeNumber": "ACME-02027",
        "roles" : [
            {
                "id": "audit_examiner"
            },
            {
                "id": "audit_supervisor"
            }

        ]
    }
  }
}

Updating users

Use the following endpoint to modify an existing user:

  • PATCH /admin/v1/users/{userId}

Modifying user role assignment

You can use the PATCH /admin/v1/users/{userId} endpoint to assign or unassign roles to an existing user by modifying the roles array.

Note that, within Cloud API, PATCHing an array does not add the PATCH members to the members already existing in the array. Instead, the PATCH replaces the existing members with the PATCH members. If you want a PATCH to be additive to an array, you must first determine the existing members of the array, and then specify an array in the PATCH with the existing members as well as the ones you wish to add.

For example, suppose you have an existing user named Adriana Diaz with an ID of pc:111 and the following roles:

  • audit examiner (audit_examiner)
  • audit supervisor (audit_supervisor)

You want to add the Premium Auditor role (premium_auditor) to this user. To do so, you must use the following payload. (Note that the payload specifies the existing roles and the new role.)

PATCH /admin/v1/users/pc:111

{
  "data": {
    "attributes": {
      "roles": [
        {
          "id": "audit_examiner"
        },
        {
          "id": "audit_supervisor"
        },
        {
          "id": "premium_auditor"
        }
      ]
    }
  }
}