Skip to main content

Modifying a user

This guide explains how to update an existing user in the Stonal platform using the API. Similar to user creation, updating a user requires gathering current information before making changes.

Prerequisites
  • API access credentials
  • A valid access token (see: Get a token)
  • An organization code
Update by email

If you wish to update an existing user by email, you can follow the previous creation process, as described: Here

The creation endpoint will update the user if it already exists.

Step 1: Lookup the user information that needs change​

User groups​

Get available user groups:

See: API Specification

GET /v1/organizations/:organizationCode/groups?pageNumber=1&pageSize=10

The resulting groups can be used to create a user with the groupUids field.

Application groups​

Retrieve available application groups:

See: API Specification

GET /v1/organizations/:organizationCode/users/permissions?pageNumber=1&pageSize=10&type=SCOPE_GROUP&subType=APPLICATION

The resulting application groups can be used to create a user with the permissions.uid field. Thus giving the user the right to access the corresponding applications.

Profiles​

Get available user profiles:

See: API Specification

GET /v1/organizations/:organizationCode/users/permissions?pageNumber=1&pageSize=10&type=PROFILE

The resulting profiles can be used to create a user with the permissions.uid field.

Assets​

Here is the list of currently available ASSET subtypes:

  • PORTFOLIO
  • COMPANY
  • FACILITY
  • BUILDING_GROUP
  • BUILDING
Companies​

See: API Specification

GET /v1/organizations/:organizationCode/users/permissions?pageNumber=1&pageSize=10&type=ASSET&subType=COMPANY

The resulting permissions can be used to create a user with the permissions.uid field. Thus giving the user the right to access the corresponding companies.

Portfolios​

See: API Specification

GET /v1/organizations/:organizationCode/users/permissions?pageNumber=1&pageSize=10&type=ASSET&subType=PORTFOLIO

The resulting permissions can be used to create a user with the permissions.uid field. Thus giving the user the right to access the corresponding portfolios.

Step 2: Update the user​

Update the user with the modified information:

See: API Specification

PUT /v2/organizations/{organizationCode}/users/{uid}

Request body:

{
  "email": "firstName.lastName@corp.com",
  "firstName": "firstName",
  "lastName": "lastName",
  "password": "SecureP@ssw0rd!",
  "fromExternalIdp": false,
  "allAssets": false,
  "userGroupUids": [
    "019619df-4768-76b7-81e3-2c56d374df46"
  ],
  "permissions": [
    {
      "uid": "019619df-4767-730f-8d31-143712a08141"
    },
    {
      "uid": "019619df-4767-730f-8d31-143712a08142"
    }
  ]
}

Required fields:

  • email: User's email address
  • firstName: User's first name
  • lastName: User's last name
  • groupUids: Array of group UIDs
  • permissionUids: Array of permission UIDs

Possible responses:

  • 200: User updated successfully
  • 404: User not found

Key Differences from Creation​

When updating a user, note these important differences:

  1. Email address cannot be modified
  2. Use PUT instead of POST method
  3. Requires user UID in the path

Important Considerations​

  1. Partial Updates: The API does not support partial updates. You must provide all required fields in the update request, even if you're only changing one value.

  2. Permissions:

    • Provide the complete new set of permission UIDs
    • All existing permissions will be replaced
    • All permission UIDs must be valid

Error Handling​

Common error scenarios:

  • User isn't found (404)
  • Invalid group UIDs
  • Invalid permission UIDs
  • Missing required fields

Best practices​

  1. Always retrieve current user data before updating
  2. Validate all new values against the lookup endpoints
  3. Keep track of sensitive changes (permissions)
  4. Implement proper error handling for 404 responses