New User Invitation Workflow
The New User Invitation Workflow is tailored for onboarding individuals new to an application. It includes sending invitations, guiding users through the initial setup, and creating an account. The user does not exist in Wristband before accepting a New User Invitation.
This contrasts with the Existing User Invitation Workflow, which is for inviting users already within the system, encouraging ongoing engagement and platform utilization. This workflow is ideal for administrators who provision users in Wristband in advance and then intend to send them an email, granting them self-access at a later point.
When a user lands on the New User Invitation Page, they will be prompted to enter additional information before their account is created in Wristband. The possible form fields a user must fill out mirror those of the Signup Workflow and depend on how your application and/or tenant is configured.
How to Send New User Invitations
There are two main ways to send New User Invitations: from the Wristband Dashboard and programmatically from your application.
From the Wristband Dashboard, you can find the New User Invitation form on the Users Page in both Application View and in Tenant View.
For programmatic invocation of the New User Invitation Workflow in your application, you can call the Wristband Invite New User API.
Upon sending, the user will receive the invitation email at the provided email address. The Action Link URL in the email body can be configured for details such as expiration time and URL location on the Email Policy Page in the Wristband Dashboard.
Resending and Cancelling Invitations
Only one pending invitation for a specific email address is allowed within a tenant at any given time. If an end user has already received a New User Invitation and another application user or an admin sends a second invitation to the same end user, the first invite is automatically canceled.
There are also two ways to explicitly cancel a New User Invitation: from the Wristband Dashboard and programmatically from your application.
From the Wristband Dashboard, you can find the New User Invitations table on the Users Page in both Application View and in Tenant View.
For programmatic cancellation of the New User Invitation Workflow in your application, you can call the Wristband Cancel New User Invite API.
Assigning User Roles During Invitation
In both scenarios, the Invite API includes a request body field named rolesToAssign
. This field enables you to optionally assign one or more roles to a user before they conclude the workflow. Upon accepting the invitation, the end user will be assigned the specified roles before initiating their first interaction with the application.
User Schema
If your application's User Schema includes required fields, these fields will be displayed on the New User Invitation Form (with the exception of externalId). Depending on application and/or tenant configurations, possible fields that can appear on the New User Invitation form include:
- Full Name
- Given Name (First Name)
- Family Name (Last Name)
- Phone Number
- Birthdate
- Username
- Password
Redirecting Back to Your Application
When concluding the New User Invitation workflow, Wristband typically redirects the user to your application's Login endpoint to initiate the Authorization code flow. At this juncture, the Wristband authentication session has already been established, enabling your application to acquire an access token without prompting the user to re-enter credentials on the Login Page. However, it is possible that Wristband could redirect the user to a different URL aside from your application's Login Endpoint depending on a few configurations.
The final destination URL that Wristband redirects to at the end of the New User Invitation workflow is resolved in the following order:
- Check if a custom redirect URL is enabled in the New User Invitation Workflow Policy at the Tenant level for the tenant which the user is being invited into.
- Check if an OAuth2 Client login URL is configured for the Client through which the user is accepting the invitation with.
- Default to using the Application login URL.
Updated 4 months ago