Handle user invitations via CustomerID REST API

This article gives an overview how to create, list, query, resend and delete user invitations by using the CustomerID REST API.

It is possible to handle creation and management of new users and the invitation process using CustomerID REST APIs. Typically a target application includes the relevant calls within the target application user interface. See Complex invitation form example using CustomerID API for an example.

Introduction to Pending User concept

When populating a new system with users from an existing list, such as an excel spreadsheet or CSV file, there are two different techniques:

The API call MOD009 Create User will create a user account that is ready to use. This is usually used when all of the information about a user is already known, including the password. It assumes that the user has somehow already given consent for having an account created (e.g. based on an existing contract or based on a third-party user interface shown before invoking this command)
Roles can be assigned to user immediately after creation.

See MOD009 Create User API call.



The second method is the API call MOD026 Create Pending User. This call will create a user account that is not yet activated. The Ubisecure CustomerID system will send an email invitation to the user, inviting them to follow a link to activate the account. During activation, the user will have a chance to interactively approve any terms and conditions, set a password, change or modify any permitted attributes and enable strong authentication methods, such as SMS OTP and Print out OTP.
Roles cannot be assigned to a pending user before it the invitation has been accepted.

See MOD026 Create Pending User API call.

A call to either command will be required for each new user to be added.

Create user invitation

Use operation MOD026 (Create Pending User):

POST /customerid-rest/services/pendingusers?username=restuser&password=***&Registration=roleinvite&email=Firstname.Lastname@example.com&firstname=Firstname&surname=Lastname&login=Firstname.Lastname@example.com HTTP/1.1
Host: account.test1.onubisecure.com

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<idlist>
    <id>https://account.test1.onubisecure.com/customerid-rest/services/pendingusers/762983ae-ead7-4e3a-9281-a21898dafd4c</id>
</idlist>

Depending on your use case, you might want to save the resulting CustomerID internal user ID (762983ae-ead7-4e3a-9281-a21898dafd4c above) to the user profile of your application. It is not straightforward to fetch the invited user e.g. by using the email address.

Query/modify invited user

If you have stored the CID user ID, you can simply use the operation REQ002 (Query User) to get the user attributes. Status "Pending" indicates that the user has not yet used the registration link in the invitation email.

GET /customerid-rest/services/2.0/users/762983ae-ead7-4e3a-9281-a21898dafd4c?username=restuser&password=*** HTTP/1.1
Host: account.test1.onubisecure.com

<User xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="/2.0/users/762983ae-ead7-4e3a-9281-a21898dafd4c" method="GET" type="user">
<Attribute name="id">
<Value>762983ae-ead7-4e3a-9281-a21898dafd4c</Value>
</Attribute>
<Attribute name="firstname">
<Value>Firstname</Value>
</Attribute>
<Attribute name="surname">
<Value>Lastname</Value>
</Attribute>
<Attribute name="login">
<Value>Firstname.Lastname@example.com</Value>
</Attribute>
<Attribute name="email">
<Value>Firstname.Lastname@example.com</Value>
</Attribute>
<Attribute name="status">
<Value>Pending</Value>
</Attribute>
</User>

You can use the operation (MOD004 Update User) to modify the attributes of the invited user. This may be useful for example if the user name was incorrect in the original invitation and it was later corrected. Note that no new invitation email will be sent, but the user will see the updated values in the account registration form.

PUT /customerid-rest/services/2.0/users/83feff21-c9fa-44f5-9421-be7d4fe7c23b?username=restuser&password=***&firstname=Anothername HTTP/1.1
Host: account.test1.onubisecure.com

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Users 
    xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="/2.0/users/83feff21-c9fa-44f5-9421-be7d4fe7c23b" method="PUT">
    <Id>83feff21-c9fa-44f5-9421-be7d4fe7c23b</Id>
</Users>

Resend a user invitation

There is no direct way to generate a new invitation message if for example the invitee has lost the original message or the email for some reason couldn't be delivered. CustomerID will automatically send the invitation link again within reminder messages according to the configuration. If the invitation explicitely must be sent again, you can delete the invited pending user (example follows later in this article) and generate a new invitation by using the operation MOD026 (Create pending user).

It is also possible to generate the invitation link and send it directly to the invitee without using CustomerID. Here is an example invitation email generated by CustomerID when using MOD026 (Create pending user):

Dear Firstname Lastname,

You are invited to use Customer A services.

Please create an account and set a password here:
https://account.test1.onubisecure.com/eidm2/wf/register/roleinvite/9b9ae8cf-6e3a-4d98-9b8d-7649387340f3

NOTE: Do not reply to this address.

You can compose the registration link by using the operation REQ015 (Query Registration):

GET /customerid-rest/services/pendinguser/762983ae-ead7-4e3a-9281-a21898dafd4c?username=restuser&password=*** HTTP/1.1
Host: account.test1.onubisecure.com

<pendingUser>
   <userid>762983ae-ead7-4e3a-9281-a21898dafd4c</userid>
   <pendinguserid>9b9ae8cf-6e3a-4d98-9b8d-7649387340f3</pendinguserid>
   <registrationwf>roleinvite</registrationwf>
</pendingUser>

List all user invitations

Use the operation REQ013 (List Registrations) to list all pending user invitations:

GET /customerid-rest/services/pendingusers/?username=restuser&password=*** HTTP/1.1
Host: account.test1.onubisecure.com

<idlist>
<id>https://account.test1.onubisecure.com/customerid-rest/services/pendinguser/1c008667-506f-4763-8da6-2f4d6a00bcb7</id>
<id>https://account.test1.onubisecure.com/customerid-rest/services/pendinguser/637a6b3e-e2a1-4624-8a8d-dba08bb13a18</id>
<id>https://account.test1.onubisecure.com/customerid-rest/services/pendinguser/5948d0ed-e89d-4148-a8ab-b1fb24ee4049</id>
</idlist>

You can then use REQ002 (Query User) to get attributes of each pending user.

Delete user invitation

If you need to delete an invitation completely, use MOD010 (Delete User):

DELETE /customerid-rest/services/2.0/users/762983ae-ead7-4e3a-9281-a21898dafd4c?username=restuser&password=*** HTTP/1.1
Host: account.test1.onubisecure.com

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Users 
    xmlns="http://schema.ubisecure.com/customerid/api" inResponseTo="/2.0/users/762983ae-ead7-4e3a-9281-a21898dafd4c" method="DELETE">
    <Id>762983ae-ead7-4e3a-9281-a21898dafd4c</Id>
</Users>

Summary

Using the above APIs it is possible to implement creation and management of new users and the invitation process. Typically a target application includes the relevant calls within the target application user interface. See Complex invitation form example using CustomerID API for an example.

Related articles

• Page:
  Handle user invitations via CustomerID REST API