Inviting Users

This guide will cover how to implement user invitations within Descope. Descope allows for several mechanisms to invite users and provides for invitation customization and templates for the invitation. These items are covered below.

User Invitations

Configuring the invitation can be completed within the Project Settings page.

Below is an overview of the configurations.

• The connector is whether the invitation email is sent with the Descope email connector or your configured SendGrid or SMTP connector.
• The template is where you can add a template to customize your invite email when using a connector. When using the Descope connector, custom templates are unavailable.
• The Redirect URL is the URL which the user will receive in their invite email.
• Add a Magic Link token to the invitation email - when this checkbox is selected, the user will also receive a magic link within the invitation email. Once selected, you can also set the Invite Token Expiration.

Templates

When you utilize an email connector instead of the Descope system connector, you can create multiple templates for user invitation. The ability to have multiple templates allows you to create tenant or role specific templates to better customize your user experience.

The templates are written via formatted HTML code. When customizing a template, you can utilize {{}} to add dynamic Descope values for the project, user, tenant, etc. The templates can also be edited in plain text.

Below is an example of a customized email template with an embedded image.

You can also preview the email by clicking the preview tab.

This email invitation template also supports user attributes as dynamic values. This applies for system as well as custom attributes (ex: dob, plan, position etc.). Similar to how values for project, user, tenant etc. were added, you can now extract custom attributes utilizing {{}}.

Below is an example showcasing the dynamic values:

With this configuration of the email template, you can incorporate additional parameters like user's name or their phone number, loginIds etc using user. and custom attributes using unauthUser.customAttributes.

Inviting Users

Descope Console

Within the User page inside the Descope console, you can invite users in bulk, singularly, add tenants and roles to the invite, and select a customized invite template. Below is an example of inviting multiple users with a custom email template and associating the user to a tenant and roles.

You can also create a new user with multiple Login IDs by adding emails and/or phone numbers in the user attributes, and selecting the "Add As Login Id" option.

Descope Flows

You can add user invites within your flow. A use case for this would be to embed a flow within your application to allow admins to log in or, within your login flow, to ask the user on initial sign up to invite users.

Invite During Initial Sign Up

Here is an example of a flow that prompts the new user to invite users after they have successfully authenticated.

Within this example, we added an additional screen after the user is authenticated and checked if it's a new user. We prompt the user if they would like to add new users and provide them with the Invite User text box where they can pass a comma separated list of users.

Configuring the User/Invite Action

Now, you'll add the User/Invite action by clicking the blue + at the top of the flow builder, selecting actions, searching for User / Invite, and adding it. Once added to the flow, you can configure the connector, template, roles, and whether only tenant admins or everyone can send an invite. You can also configure template options via dynamic keys. Below is an example of a modified User/Invite action, including the dynamic keys for the template.

Once you have configured the template options within the flow, you can edit and use these dynamic keys in your invite template. Similarly to how we document using template options here.

Invite Using an Embedded flow

Similar to the above example, you add a screen and an invite action. You can customize both of these items to fit your needs. Within this flow, you can also add a condition to check if the user is authenticated and have them log in if they are not yet authenticated.

Updating User Roles

You can also use the Update User / Add Roles action to modify the user's role after invitation, on the project or the tenant level:

Descope Management SDK

You can also invite users via the Descope Management SDK. The details can be found here.

Include Magic Link in User Invite

Configure the Project Settings

The first step will be to check the box for Add a Magic Link token to the invitation link within your project settings.

Updating Your Flow

You will need to add a condition to the beginning of your flow which checks if the externalToken is present. You will need to click the blue + at the top left of the flow editor and select condition. You can then configure the condition as seen below.

Then you will need to add the Verify Token action to your flow. You can add it by going to the blue + at the top left of the flow editor and then searching for the action after clicking action. Once added, connect the applications similarly to the below example.

Inviting Users vis SMS

Descope also supports inviting users via SMS. You can configure templates similarly to the email templates when you have a customized SMS connector like Twilio configured.

Within the console, you can configure to send SMS invites as well as the template within the Project Settings page. If you have checked the boxes for sending email and SMS invites, when inviting from the user's page, the default behavior will be to send the invite via email.

To force sending invites via SMS, you can utilize the Descope Management SDK or API.