Signup Workflow

In Wristband, users can sign up at two levels of the application. Each signup type has distinct implications.

Signup URLs for Wristband-hosted Pages

There are publicly available URLs where you can reach the Wristband-hosted Signup Pages for both the Application level and the Tenant level (if enabled).

Wristband Vanity Domains

Let's say we had a Wristband application named "Your App" with an application domain name of yourapp. Let's also say that if the application was multi-tenant there was a tenant "Your Customer" with a tenant domain name of yourcustomer. The various signup URLs would look like the following:

Signup Type	URL
Application Level	`https://yourapp-yourcompany.us.wristband.dev/signup`
Tenant Level	`https://yourcustomer-yourapp-yourcompany.us.wristband.dev/signup`

Custom Domains

If you had the custom domain auth.yourapp.io enabled for your application, the various signup URLs would look something like the following:

Signup Type	URL
Application Level	`https://auth.yourapp.io/signup`
Tenant Level	`https://yourcustomer.auth.yourapp.io/signup`

Supported Query Parameters

The URLs for the Wristband-hosted Signup pages can support certain query params that will be processed and utilized by the Wristband platform. You can use the following query params for enhanced functionality:

Query Parameter	Description
`client_id`	If your application accommodates multiple OAuth2 clients for authentication, you can designate the login URL that Wristband redirects to at the end of the signup process. This is achieved by specifying the clientId associated with the desired OAuth2 Client whose login URL you intend to utilize.
`state`	You can propagate any necessary arbitrary state during the signup flow by utilizing the `state` parameter. Refer to the Propagating State Through the Signup Flow section below for more details.

Login Links on Signup Forms

There are Login Action Links at the bottom of the Signup Form on all Wristband-hosted Signup Pages.

Depending on which level of Signup Page you are currently interacting with, the URL for that link should change depending on how you have implemented your application's Login Endpoint. The following is the expected mapping of Signup Pages to Login Action Link locations:

Signup Page	Login Location
Application Level	Application-level Login (Tenant Discovery must happen in order to identify a Tenant-level login URL)
Tenant Level	Tenant-level Login

Application Signup

In multi-tenant applications, users can access the Application-level Signup page. In this case, the user is not only signing themselves up for your application, but they are also provisioning a tenant for their organization upfront. The Signup Page requires providing a tenant domain name that is dedicated to their organization.

Upon successful completion of a Signup Workflow at the Application level, the following occurs:

Tenant is created with the provided domain name under the application.
User is created under the newly provisioned tenant.
If a Role Assignment Policy has been configured for the application, then the role(s) are automatically assigned to that user.

The Application-level Signup Page can only be reached using an application vanity domain as opposed to a tenant vanity domain. The login action link at the bottom of the Wristband-hosted Signup Page will point to the Application-level Login Page for your application.

You can enable or disable Application-level signup in the Application Settings section of the dashboard. If Application-level signup is disabled, users can't access the Wristband-hosted signup page, and any Wristband API with the ability to provision new users will fail to execute. Nevertheless, Tenant-level Signup Pages can still be accessed on a per-tenant basis, contingent upon whether any are enabled.

Tenant Signup

You have the option to enable Tenant Self-Signup individually for each tenant in your application. This can be done by navigating to the Tenant Settings page in the dashboard and activating the configuration for a specific tenant. Enabling Tenant Self-Signup for one tenant does not impact any other tenants. Additionally, Tenant Self-Signup operates independently of Application-level Signup configuration. You can have Application-level signups without enabling Tenant-level signups, and vice versa—enabling Tenant-level signups while simultaneously disabling Application-level signups is also possible.

As Tenant Self-Signup is specific to just one tenant, the owning organization usually restricts allowed email domains for this process. For instance, Acme may only permit employees with email addresses from the acme.com domain. You can manage the allowed email domains for Tenant Self-Signup in the same dashboard section as the toggle switch for Tenant Self-Signup.

Upon successful completion of a Tenant Self-Signup Workflow, the following occurs:

User is created under the tenant for which they are signing up.
If a Role Assignment Policy has been configured for the application, then the role(s) are automatically assigned to that user.

The Tenant-level Signup Page can only be reached using a tenant vanity domain. The login action link at the bottom of the Wristband-hosted Signup Page will point to the Tenant-level Login Page for your application.

If Tenant-level signup is disabled for a particular tenant, then users can't access the Wristband-hosted signup page for that tenant, and any Wristband API with the ability to provision new users into that particular tenant will fail to execute.

User Schema

If your application's User Schema includes required fields, these fields will be displayed on the signup form for both Application-level and Tenant-level signups (with the exception of externalId). Depending on application and/or tenant and configurations, possible fields that can appear on the Signup form include:

Tenant Domain Name
Email
Full Name
Given Name (First Name)
Family Name (Last Name)
Phone Number
Birthdate
Username
Password

User Activation vs Email Verification

In the Workflow Policy section of the dashboard, you can customize how users are initially logged into the application after completing signup. Two options are available: user activation signup and email verification signup.

User Activation

When user activation workflow policy is selected, users will receive an activation email containing an email action link after completing the signup form. By clicking on this link, users verify their email address and activate their account. This step enhances security by confirming the legitimacy of user-provided information and helps prevent unauthorized access. Once activated, users can log in and fully utilize the application's features.

When a user signs up for your application but has not yet clicked the activation email link, they are in the PROVISIONED state. In this state, if the user fails to click the link before it expires, they can initiate the signup workflow again. This will trigger the sending of a new activation email, provided they sign up using the exact same email address (and tenant domain name if multi-tenant).

Email Verification

When email verification workflow policy is selected, users will get logged into your application after completing the signup form. The user will also asynchronously receive an email containing a verification link. Clicking on this link confirms the validity of the email address, completing the verification process. This step enhances security, ensuring that users provide a valid and accessible email, and helps prevent misuse of the application.

When a user signs up for your application but has not yet clicked the email verification email link, they are in the ACTIVE state. However, their email will remain unverified until they click the link.

Redirecting Back to Your Application

When concluding the Signup 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 Signup workflow is resolved in the following order:

Check if a custom redirect URL is enabled in the Signup Workflow Policy at the Tenant level for the tenant which the user is signing up into.
Check if an OAuth2 Client login URL is configured for the Client through which the user is signing up.
Default to using the Application login URL.

Propagating State Through the Signup Flow

You can propagate any necessary arbitrary state during the signup flow by utilizing the state parameter. This is accomplished by incorporating the state parameter when executing a signup workflow. This feature is valuable for various product scenarios, including the application of promo codes. If needed, you can also encode a JSON object into a string to address more complex product requirements.

Wristband-Hosted Signup State

When utilizing Wristband-hosted signup pages, you can navigate to either the Application-level or Tenant-level signup pages while including the state query parameter in both instances. The Signup Page communicates this query parameter to Wristband through API requests. Upon the successful completion of the Signup workflow, Wristband redirects back to your application, preserving the state value query parameter.

Self-Hosted Signup State

When self-hosting any signup pages for your application, it is up to you to pass any state values to Wristband when invoking Wristband APIs. Refer to the Provision Wristband IDP User on Signup API or Authorize External IDP User on Signup API documentation for details on how to work with it.