Skip to main content

Creating a user

This guide walks through the process of creating a new user in the Stonal platform using the API. The process involves several steps to gather required information before creating the user.

Prerequisites
  • A valid set of API credentials
  • A valid access token (see: Get a token)
  • An organization code

Step 1: Search for an existing user​

Before creating a new user, check if they already exist to avoid duplicates.

See: API Specification

GET /v2/organizations/{organizationCode}/users?pageNumber=1&pageSize=10&q=firstName.lastName@corp.com

If the user exists, you'll receive a 200 response with user details (See: Modifying a user). If not, proceed with user creation.

Step 2: Lookup the necessary user information​

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 3: Create the user​

Finally, create the user with all gathered information:

See: API Specification

POST /v2/organizations/{organizationCode}/users

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 created successfully

Notes​

  • All email addresses must be unique in the system
  • The password, if defined, must be at least 8 characters long and contain at least one uppercase letter, one lowercase letter, one number and one special character.
  • If fromExternalIdp is true, the user must authenticate through their identity provider
  • Asset access can be granted to all assets ("allAssets": true) or specific assets using the permissions.uid field
  • Permission UIDs must be valid and retrieved from the permissions endpoint

Error Handling​

Common error scenarios:

  • Duplicate email address
  • Invalid permission UIDs
  • Missing required fields

Always check the response status and handle errors appropriately in your implementation.