Invite users

This article guides you how to invite users through the 10Duke Identity Management REST API.

In the case of B2B customers, it’s a common approach that the onboarding of users is handled by each customer organization using the OrgAdmin tool.

However, you (the vendor) also have the options of handling user onboarding yourself using the SysAdmin tool or of automating it by integrating 10Duke APIs to your other systems, such as a customer relationship management (CRM) or e-commerce system.

With B2C customers, a common approach is to onboard the users by providing self-registration.

Overview

You can use invitations to create all types of users through the Identity Management REST API: the users of your B2B customer organizations (including their administrator users), your B2C consumer users, and your own system administrators.

You can also use invitations to add existing users to an organization.

Associating users with an organization

If you’re using invitations to create users for a customer organization, you associate them with the organization by adding them to the organization’s user groups. Each new organization is by default created with an “employees” user group that has built-in default authorization logic.

When the invited users need administrator access to the organization, assign them organization roles. Each new organization has a default “OrgAdmin” organization role for granting administrator access.

You can also use invitations to add existing users to an organization’s user groups or grant them administrator access. Matching to existing users in 10Duke Enterprise is based on the email address in the invitation. If the specified email address isn’t found in any user account, a new user account is created.

Accepting an invitation

A user needs to accept their invitation for their new access rights to take effect. To accept an invitation, the user must be authenticated, so an existing user must log in and a new user must register as a user.

The 10Duke Login Application component provides UI pages where users can accept and decline invitations, log in, and register, but you can also implement custom pages to suit your specific requirements.

If you redirect users to a custom page from the invitation email, the external URL must be whitelisted in 10Duke Enterprise.

Invitation token

Access to an invitation is controlled with an invitation token (a random character string). The token authorizes the specified recipient to access the invitation to accept or decline it.

  • If you’re using 10Duke Enterprise to send the invitation email, 10Duke Enterprise generates the token for the invitation when sending it.

  • Depending on your use case, you can also generate and retrieve a token for an invitation through the Identity Management REST API, and provide it to the recipient by some other means—for example, as part of a URL that opens a welcome page where they can accept or decline the invitation.

Invite a user to an organization

Use an invitation that gives the user access to an organization through specified user groups and organization (administrator) roles. For a new user, a user account is created in the system after registration.

Depending on your use case, you can:

The Login Application component handles the accepting and declining of the invitation. If you’re providing a custom UI page for users to accept and decline invitations, use PUT /organization-group-invitations/accept to accept an invitation and PUT /organization-group-invitations/decline to decline it.

If you need to invite the first organization administrator for a new organization that you haven’t created yet, you can use the same process as when inviting consumer users (see below).

Invite a consumer user

Use an invitation that creates a new user account in the system after registration.

  1. Create an invitation in the system using POST /user-invitations.

  2. Either send the invitation through 10Duke Enterprise using PUT /user-invitations/{invitationId}/send, or generate an invitation token using POST /user-invitations/{invitationId}/create-token and provide the token to the recipient by some other means.

You can also use this to invite the first organization administrator for a new organization you’re about to set up.

The Login Application component handles the accepting and declining of the invitation. If you’re providing a custom UI page for users to accept and decline invitations, use PUT /user-invitations/accept to accept an invitation and PUT /user-invitations/decline to decline it.

Invite a system administrator

To invite your own system administrators, use the same process as when inviting consumer users (see above).

The only difference is that the request for creating the invitation must specify the necessary internal roles to grant system administrator access.

Next steps

Alternatives to using invitations

Instead of using invitations, which users have to accept for the changes to take effect, the Identity Management REST API also provides other options such as:

Note that these API operations only create a user account without a password. You must provide some other way for users to create a password for themselves to be able to log in.

One option is to send an account activation email to the user through 10Duke Enterprise, either using parameters in the create or import operation or using a separate API operation. The account activation email provides a link to open the account activation page in 10Duke Enterprise, where the user can define a password for themselves.

On this page