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

POST /v1/organizations/{organizationCode}/users/search

Request body:

{
  "email": "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​

Get the list of available companies that can be assigned to the user:

See: API Specification

GET /v1/organizations/{organizationCode}/users/companies

Query parameters:

  • page (optional): Page number (default: 0)
  • size (optional): Items per page (default: 100)

The resulting companies can be used to create a user with the company field. Thus giving the user the right to access the assets of the corresponding company.

Step 3: Create the user​

Finally, create the user with all gathered information:

See: API Specification

POST /v1/organizations/{organizationCode}/users

Request body:

{
  "email": "firstName.lastName@corp.com",
  "firstName": "firstName",
  "lastName": "lastName",
  "company": "companyName",
  "fromExternalIdp": false,
  "groupUids": ["0192d7b7-2994-7ad5-9952-26862f33c21a"],
  "authorization": {
    "modelId": "2b2e8a4b-bfbd-4c56-b8d6-c8cb1d8c58ba",
    "profile": "Developer",
    "asset": {
      "all": false
    }
  },
  "permissionUids": [
    "0192d7b7-2994-7ad5-9952-26862f33c21a",
    "0192d7b7-7073-7e58-896c-07113f22363a"
  ]
}

Required fields:

  • email: User's email address
  • firstName: User's first name
  • lastName: User's last name
  • company: Company name (must be from available companies)
  • groupUids: Array of group UIDs
  • authorization: Authorization configuration
    • modelId: ID of the authorization model
    • profile: User profile
    • asset: Asset access configuration
  • permissionUids: Array of permission UIDs

Possible responses:

  • 201: User created successfully
  • 202: User creation appears successful but cannot be confirmed
  • 409: User already exists

Notes​

  • All email addresses must be unique in the system
  • The company assignment affects which assets the user can access
  • If fromExternalIdp is true, the user must authenticate through their identity provider
  • Asset access can be granted to all assets ("all": true) or specific assets using permissionUids
  • Permission UIDs must be valid and retrieved from the permissions endpoint

Error Handling​

Common error scenarios:

  • Invalid authorization model ID
  • Invalid company name
  • Duplicate email address
  • Invalid permission UIDs
  • Missing required fields

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