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.

Report groups​

See: API Specification

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

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

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
Account-activation emails and fromExternalIdp

The fromExternalIdp flag is what controls whether Stonal sends the new user an account-activation email (the "Set your STONAL password" message). It is the only setting that governs this behaviour for the API — the organization's front-end SSO toggle has no effect on it.

  • fromExternalIdp: false (the default) — the account is created with a local password and the user receives the activation email so they can set or confirm their password. If you omit the field, it defaults to false, so the email is sent.
  • fromExternalIdp: true — the account is treated as federated: no activation email is sent and the user must authenticate through their external identity provider (SSO).

If your users sign in through SSO and you do not want them to receive the "Set your STONAL password" email, you must explicitly pass "fromExternalIdp": true in the create call. Leaving it at false (or omitting it) for SSO users is the most common cause of unexpected activation emails.

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.
  • fromExternalIdp controls both authentication and email behaviour: when true, the user authenticates through their identity provider and no activation email is sent; when false (default), an activation email is sent so the user can set a local password (see the warning above).
  • 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.