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​

Verify 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 update a user with the company field. Thus giving the user the right to access the assets of the corresponding company.

Step 2: Update the user​

Update the user with the modified information:

See: API Specification

PUT /v1/organizations/{organizationCode}/users/{id}

Request body:

{
  "firstName": "updatedFirstName",
  "lastName": "updatedLastName",
  "company": "updatedCompanyName",
  "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:

  • 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

Note: Unlike creation, the update request doesn't include the email address as it cannot be modified.

Possible responses:

  • 204: 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 ID in the path
  4. Returns 204 (no content) on success instead of 201

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. Asset Access:

    • When modifying asset access, provide the complete new set of asset codes
    • Setting "all": true overrides any specific permissions for the asset type

  3. Permissions:

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

  4. Authorization Model:

    • Changing the authorization model might affect user's access to various features
    • Ensure the new model provides appropriate access levels

Error Handling​

Common error scenarios:

  • User not found (404)
  • Invalid authorization model ID
  • Invalid company name
  • Invalid group UIDs
  • Invalid permission UIDs
  • Missing required fields
  • Invalid format of asset codes

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 (authorization, permissions)
  4. Implement proper error handling for 404 responses