Skip to content
Identity and Access Management

User Management

IAM supports the management of users with or without email addresses. These users can sign in to Trimble Identity using the same login screen. To onboard users into the IAM system, follow these steps:

Prerequisites

  • Ensure that accounts are set up, and an admin or owner user is designated.
  • Users without an email address can only be created or added to accounts that have a short code configured.

IAM Resource

IAM Roles

Role nameStaging IDProduction ID
ownerb1bdb748-8e73-47c9-97e6-a8ed63fe294dd9c39877-26f6-482c-a35f-53f68c952374
admina6c7f82e-f754-4cd0-83ba-71f5584d427236e43d21-bd57-4d57-bbd1-2e5a56ab3904
secondary_owner5f6b679e-2866-41ae-8dfe-55ebc31281d05fac689e-ce34-4a8d-91c8-e0bdfcac6e92
end_userc0e0df24-4d44-4738-ad65-14770658e73c4916d841-fedb-4cfd-96b9-edfcf35fbe7c

IAM Application ID

StagingProduction
695d741b-2f4a-4cb8-8d97-e81fd4dbd765c55271dd-2c50-4546-b946-bfe81fa121c9

User Addition

Users can be onboarded by providing either an email address or a combination of a username and temporary password, depending on the specific requirements of the application or system. To add a new user, use the POST /users or POST /invitation endpoint. These endpoints allow you to add a new user to the account (in the JWT) of the calling subject. An account can also be passed as a query parameter accountId.
For users with an email address, an invitation workflow is triggered to onboard the user into the account and to provide their consent. For users without an email, known as managed users, a workflow is used in special cases to support alternate authentication methods by setting up a username and a temporary password on behalf of users who do not want to use their email IDs. Managed users do not receive invitations and can only be linked to a single account.

Note: A managed user can only be added to an account that has a short code. For more details on short code refer How to add short code

A list of roles to be assigned can be specified using the roleIds query parameter. Applications can assign roles that are either created by themselves or by other applications. Roles created by other applications can be shared via a trusted group, provided that the application is a member of this trusted group. However, to use IAM roles additional access must be granted. To obtain this access, a support ticket must be raised, including the Application ID and a business justification for why the IAM roles is required. The information about each stack’s IAM roles can be found below.

Sample Managed User API Call

 POST `/users?accountId=19512863-ce90-4000-87c7-7b1571e44f01&roleIds=["b1bdb748-8e73-47c9-97e6-a8ed63fe294d"]

Header

  • Authorization: Bearer {tid token}

Query Parameters

  • accountId TThis is the unique identifier of the account to which the user is being invited. It is an optional parameter. If not given, the user will be invited to calling subject’s account.
  • roleIds An optional field where you can specify a list of roles to be assigned to the user.

Body

  • firstName - The user’s first name. This is the given name or personal name of the user.
  • lastName - The user’s last name. This is the family name or surname of the user.
  • country - The country where the user resides. This should be a valid country name as per the ISO 3166-1 alpha-2 standard. Refer API Spec for supported country
  • state - The state or province where the user resides and is currently mandated only for US and Canada. This should be a valid state name as per the ISO 3166-1 alpha-2 standard. Refer API Spec for supported states.
  • language - The user’s preferred language. This is used to personalize the user experience by displaying content in the chosen language. Refer API Spec for supported languages
  • timezone - The user’s timezone. This is used to display times in the user’s local timezone. Should be a BCP 47-compatible timezone designator with short codes from Unicode CLDR.
  • userName - The user’s username. This is required for managed users who do not have an email address.
  • tempPassword - The default policy for tempPassword requires it to be alphanumeric, containing at least one number, one uppercase letter, and one lowercase letter. The only allowed special characters are the underscore (_) and hyphen (-). The tempPassword will expire in 180 days.
Example Request Payload for Create Users:


```json
{
      "firstName": "Alice",
      "lastName": "Smith",
      "userName": "alice",
      "country": "US",
      "state": "US-CA",
      "language": "en-US",
      "tempPassword": "Password123"
}

Sample Email User API Call

To invite users with an email address, use the following API call:

POST /invitation?accountId=19512863-ce90-4000-87c7-7b1571e44f01&redirect_url=https://www.example.com

Query Parameters

  • accountId This is the unique identifier of the account to which the user is being invited. It is an optional parameter. If not given, the user will be invited to calling subject’s account.
  • redirect_url: This is the URL to where the user will be redirected after accepting the invitation. It is an optional parameter. If not given, the user will be redirected to their myprofile page.

Body

  • email - The user’s email address, used for login and communication purposes. This is required and must be unique.
  • roleIds - An optional field where you can specify a list of roles to be assigned to the user.

Example Request Payload for Creating Users with Email:

{
      "firstName": "John",
      "lastName": "Doe",
      "country": "US",
      "state": "US-NY",
      "language": "en-US",
      "timezone": "usnyc",
      "email": "john.doe@trimble.com",
      "roleIds": ["b1bdb748-8e73-47c9-97e6-a8ed63fe294d"],
      "emailTemplates":
      {
         "newUserTemplateId": "3afbe6a3-cb41-561e-b9da-445ee96aa7c9",
         "existingUserTemplateId": "08681ec2-7d8a-5f42-b6c1-466fee9b1336",
         "variables": {
           "name": "testTemplate"
         }
      }
}

Note: The emailTemplates field is optional and enables you to specify custom templates for new and existing users. The variables field allows you to include dynamic content in these templates. To use custom email templates, Reach out to support to have them configured for the IAM application.

User Listing

To list all users in an account, use the GET /users endpoint. This endpoint allows you to filter the results using various query parameters such as accountId and q (a filter query in RSQL format). Supported attributes for filtering include name, email and role of the user in the account. The response will provide a list of users or indicate any issues with the request. To fetch information about a specific user, use the GET /users/{userId} endpoint. This endpoint requires the userId parameter to identify the user. The response will provide the user’s information or indicate if the user was not found or if there were any issues with the request.

User Update

To update an existing user’s information, use the PUT /users/{userId} endpoint. This endpoint requires the userId parameter and a JSON object representing the updated user information. All fields in the request payload are optional. You can include only the fields that need to be updated.

Example Request Payload for Updating Users with Email:

{
      "firstName": "John",
      "lastName": "Doe",
      "country": "US",
      "state": "US-NY",
      "language": "en-US",
      "timezone": "usnyc",
      "email": "john.doe@trimble.com"
}

Example Request Payload for Updating Users without Email:

{
      "firstName": "Alice",
      "lastName": "Smith",
      "userName": "alice",
      "country": "US",
      "state": "US-NY",
      "language": "en-US",
      "tempPassword": "Password123"
}

Note: If the tempPassword is updated (password reset) for managed users, it will override the previous password set during the sign-in flow and create a new temporary password for the user. Upon signing in after this update, the user will be prompted to set a new password.

Role Assignment

Role assignment in IAM is a critical step that determines what actions a user can perform within an account or application. Roles define a set of permissions, and assigning the right roles ensures users have appropriate access based on their responsibilities.

When Are Roles Assigned?

  • During User Creation: Roles can be assigned at the time of user onboarding by specifying the roleIds parameter in the API request. This allows the user to have the necessary permissions to work in their accounts. Refer spec
  • Post Creation: Roles can also be assigned or updated after the user has been created. This is useful when a user’s responsibilities change or when additional access is required. Refer spec

Role Scope and Restrictions

  • Application Ownership: Only roles that belong to a particular application can be assigned to users of that application. This ensures that users do not receive permissions outside the intended scope.
  • Trusted Groups: Roles created by other applications can be shared via trusted groups. An application must be a member of a trusted group to assign such roles to its users.
  • IAM Roles: Special IAM roles, require additional access. To use these, a support ticket must be raised with the Application ID and a business justification. Refer IAM role table.

Best Practices

  • Assign only the minimum set of roles required for a user to perform their job (principle of least privilege).
  • Regularly review user roles to ensure they are up to date and remove unnecessary access.
  • Document the purpose of each role and the permissions it grants for easier management and auditing.

Role Retrieval

You can easily view the roles assigned to a user using the GET /users/{userId}/roles endpoint. This returns all roles currently assigned to the user, including their role IDs and details.

For more information about the API and its parameters, see the API specification for retrieving user roles.

IAM Role Retrieval

If a user is assigned an IAM role, you can retrieve these roles using the same endpoint. To list IAM-specific roles, you must include the IAM application id in the scopedToApplicationId query parameter.

Example cURL

Terminal window
curl --location 'https://cloud.stage.api.trimblecloud.com/platform/iam/1.0/users/332d9c8c-374b-4fff-8346-bd6ac78af11b/roles?on=trn%3A2%3Aiam%3Aus%3Aaccount%3A5998508f-b021-43b7-bab4-765f44ebe276&scopedToApplicationId=695d741b-2f4a-4cb8-8d97-e81fd4dbd765' \
  --header 'Authorization: Bearer <your_token>'

This will return all roles (including IAM roles) assigned to the user in the specified application context.