Tutorial: back-end user registration

This tutorial describes the API calls a backend can make in order to onboard a user in TrustBuilder.io based on an account maintained in a CRM or another IAM.

The process of onboarding a user in TrustBuilder.io can start when a new contact is created in a CRM, or by going through all existing contacts in a CRM or all accounts in an IAM. At that moment a sequence of API calls will happen to create a new user profile in TrustBuilder.io, or to update an existing user profile.

TrustBuilder.io exposes API endpoints to create/update/delete user profiles and to create/update/delete personas in an existing user profile. The TrustBuilder.io API endpoints are documented on TrustBuilder.IO API.

1.     Obtaining an access token

All TrustBuilder.io API endpoints (except the /authorize for initial user authentication) are protected by OAuth2 access tokens.

Your backend can obtain an access token through the OAuth2 client credentials grant, whereby your backend authenticates itself using its client_id & client_secret. Optionally, you can implement additional authentication protection by using private_key_jwt as documented on Client Credentials grant.

In order to create, update or delete a user profile or persona, the requested scope must include users:read, users:write as well as config:read.

2.    Registering a user profile

To onboard a new user in TrustBuilder.io, your backend calls the POST /identity/users endpoint:

3.   Adding persona(s)

After the user profile has been created, your backend can one or more personas by taking the following steps:

1. Obtain the corresponding persona definition(s)

2. Add the persona(s) to the user profile.

3.1 Obtaining persona definition ids

Personas are defined by a user with an Administrator persona. Your backend can obtain the id of a persona definition by calling GET /config/persona-definitions with the name of the persona.

Of course, this step is only needed once to obtain persona definition ids, since these remain fixed once they have been created by one of your Administrators.

3.2 Adding a persona

After the user profile has been created and assuming the set of persona definitions has been obtained, one or more such personas can be added. The user_id is the one returned in the previous step when the user profile was registered.

4.   Updating a user profile

During its lifecycle, a user profile may be updated from time to time in function of updates in your CRM. Your backend will take the following steps to reflect those changes in TrustBuilder.io:

1. Obtain the attribute definition(s)

2. Find the user profile by query & filer with the email address

3. Query the user profile to obtain the ETag

4. Update specific attributes of the user profile.

4.1 Obtaining attribute definition ids

A user profile consists of attributes. TrustBuilder.io has a set of predefined attributes, possibly extended with a number of custom attributes. Attributes are addressed by their name, as defined in the documentation for predefined attributes (see Managing User Profiles) or defined by one of your Administrators for custom attributes.

Your backend can obtain the id of an attribute definition by calling GET /identity/config/attribute-definitions with the name of the attribute (and the category in which the attribute is defined).

Of course, this step is only needed once to obtain attribute definition ids, since these remain fixed after creating the attribute definition.

4.2 Find user profile with email

your backend then calls the POST /identity/users/query endpoint of TrustBuilder.io to find the user profile using its email address.

4.3 Obtain Etag

Most TrustBuilder.io API endpoints use ETag headers to support efficient cache validation, to minimise data transfer and to ensure profile integrity when multiple calls arrive in a different order or simultanuously. The ETag (“entity tag”) header, defined by RFC 9110, is a mechanism that HTTP provides for Web cache validation and optimistic concurrency control.

An ETag is an opaque identifier assigned by an API endpoint to a specific version of a resource (such as a user profile, a policy definition or a configuration). The ETag is a hash of the resource content. Whenever the content changes, a new ETag is assigned. Used in this manner, ETags allow the API endpoints to detect whether the calling client (i.c. your backend) has and is assuming the same version of the resource content.

Using the ETag, the TrustBuilder.io platform enables optimistic concurrency control so that simultaneous updates (e.g. multiple API calls, or multiple Administrators doing an update of the same resource) of a resource do not overwrite each other.

This is actually done by the If-Match headers in the PUT and PATCH endpoints, so they can detect mid-air edit collisions and return an error. Note that POST operations do not need an ETag because they always add or replace resource contents in their entirety.

So, if no other call has not yet been made related to this user profile in the same script or procedure, the ETag must first be obtained.

4.4 Update the user profile

The final call will actually request the update. Depending on the type of update, the following endpoints are available:

• Update attributes of the user profile using PATCH /identity/users/{user_id}

• Update attributes in one of the associated personas using PATCH /identity/users/{user_id}/personas/{persona_id}

• Update custom attributes in one of the associated personas using PATCH /identity/users/{user_id}/personas/{persona_id}/attribute

In case of an attribute update inside personas, the attribute could be present in multiple personas. In that case, your backend must foresee logic to loop through all personas and send an update request for each of them.