---
updatedAt: 2026-10-16T18:20:45.000Z
agentTools:
projectIndex: https://docs.wristband.dev/llms.txt
---
# Signup Workflow
Allow users to provision themselves within your application.
The Signup workflow allows users to self-register within your application. In Wristband, signup can occur at two levels:
* Application-level Signup
* Tenant-level Signup
Each signup type has different implications for how tenants and users are provisioned, as well as the user experience throughout the signup flow.
## Application-Level Signup
When a user signs up at the application level, they are not only creating their own account but also provisioning a new tenant. The Application-level Signup Page requires providing a tenant name in order to create the tenant.
Upon successful completion of a Signup Workflow at the Application level, the following occurs:
* A tenant is created with the provided name under the application.
* A user is created under the newly provisioned tenant.
* If a [Role Assignment Policy](https://docs.wristband.dev/docs/roles#role-assignment-policies) has been configured for the application, the role(s) are automatically assigned to that user.
You can enable Application-level Signup via the **Application Settings** in the Application View of the Wristband Dashboard. If disabled, users cannot access the Wristband-hosted Application Signup Page, and the Signup link on the Wristband-Hosted Application Login Page (Tenant Discovery) will not appear. It is disabled by default.
**Note:** Tenant-level Signup Pages can still be accessed on a per-tenant basis if Tenant-level Signup is enabled for a given tenant.
## Tenant-Level Signup
When a user signs up at the tenant level, the following occurs:
* A user is created under the tenant for which they are signing up.
* If a [Role Assignment Policy](https://docs.wristband.dev/docs/roles#role-assignment-policies) has been configured for the application, the role(s) are automatically assigned to that user.
You can enable Tenant Self-Signup individually for each tenant in your application under **Tenant Settings** in the Tenant View of the Wristband Dashboard. Enabling it for one tenant does not impact any other tenants, and it operates independently of Application-level Signup.
The following can be configured per tenant:
* **Tenant Self-Signup:** Enables or disables self-signup for this tenant. If disabled, users cannot access the Wristband-hosted Tenant Signup Page for that tenant, the Signup link on the Wristband-Hosted Tenant Login Page will not appear, and Wristband APIs that provision new users into that tenant will fail to execute. It is disabled by default.
* **Allowed Signup Email Domains:** Restricts which email domains are permitted to self-signup into this tenant. Typically used when the owning organization wants to limit signups to their own domain. Maximum of 10 email domains per tenant.
***
## 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).
**Signup URLs Using Default Vanity Domains**
Let's say we had a Wristband application named `yourapp` with a tenant named `tenant1`. The various signup URLs would look like the following:
| Signup Type | URL |
| ----------------- | ------------------------------------------------------------- |
| Application Level | `https://yourapp-yourcompany.us.wristband.dev/signup` |
| Tenant Level | `https://tenant1-yourapp-yourcompany.us.wristband.dev/signup` |
**Signup URLs Using Custom Domains**
If you had custom domain `auth.yourapp.io` enabled for your application with a tenant named `tenant1`, the various signup URLs would look like the following:
| Signup Type | URL |
| ----------------- | ---------------------------------------- |
| Application Level | `https://auth.yourapp.io/signup` |
| Tenant Level | `https://tenant1.auth.yourapp.io/signup` |
### Supported Query Parameters
The URLs for the Wristband-hosted Signup pages support the following query params:
| Query Parameter | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `client_id` | If the `client_id` queyr parameter is provided, after the signup flow has completed, Wristband will redirect to the login URL configured on the specified client instead of the application's login URL. If the client doesn't have a login URL configured, then Wristband falls back to redirecting to the application's login URL. |
| `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](https://docs.wristband.dev/docs/signup-workflow#propagating-state-through-the-signup-flow) section below for more details. |
***
## How User Schema Settings Affect Signup
If your application's [User Schema](https://docs.wristband.dev/docs/users-2#updating-the-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`). Possible fields that can appear on the Signup form include:
* Tenant Name (**Application-level Signup only**)
* Email
* Full Name
* Given Name (First Name)
* Family Name (Last Name)
* Phone Number
* Birthdate
* Username (If configured as a login identifier for the Wristband IdP)
* Password (If configured as a login factor for the Wristband IdP)
***
## User Activation vs. Email Verification
After completing the Signup workflow, users will need to verify their account using one of two methods:
* **User Activation**
* **Email Verification**
The method used depends on how the **Signup Workflow Policy** is configured. The key difference is whether users must verify their accounts before they can log in or can log in immediately after signup.
### User Activation
When user activation is enabled, users receive an activation email after completing the signup form. They must complete the activation step before they can log in.
If the activation step expires before the user completes it, they can restart the Signup workflow using the same email address and, for application-level signups, the same tenant name. Wristband sends a new activation email without re-provisioning the user or tenant.
The activation experience depends on the **User Activation Strategy** configured in the **Signup Workflow Policy**:
* **Verification Link** – The user clicks the link in the activation email, which opens the activation page in a new tab and activates their account.
* **One-Time Code** – The user receives a code in the activation email and enters it on the signup page to complete activation inline.
After successful activation, the user's status transitions to `ACTIVE`, allowing them to log in to your application. Their email address is also marked as verified.
To learn more, see [User Activation Workflow](https://docs.wristband.dev/docs/user-activation-workflow).
### Email Verification
When email verification is enabled, users are immediately assigned the `ACTIVE` status, allowing them to log in to your application after completing signup. Wristband asynchronously sends a verification email to the user, and their email address remains unverified until they click the verification link.
To learn more, see [Email Verification Workflow](https://docs.wristband.dev/docs/email-verification-workflow).
***
## Redirecting Back to Your Application After Signup
At the end of the Signup workflow, Wristband typically redirects the user to your application's login URL to initiate the Authorization Code flow. Because Wristband has already established an authentication session for the user, your application can obtain an access token without requiring the user to enter their credentials on the Login page.
You can also configure the Signup workflow to redirect users to a different URL. Wristband determines the final redirect URL using the following precedence order:
1. **Signup Workflow Policy custom redirect URL** – If the Signup Workflow Policy is configured with a custom redirect URL, Wristband uses the configured redirect URL.
2. **OAuth2 Client login URL** – Otherwise, if the `client_id` query parameter was used when redirecting to the signup URL and a login URL is configured for the specified client, Wristband uses that client's login URL.
3. **Application login URL** – If neither of the above applies, Wristband defaults to the application's login URL.
***
## Propagating State Through the Signup Flow
You can pass arbitrary state through the Signup workflow using the `state` query parameter. Provide this parameter when redirecting users to the Signup URL, and Wristband will append the same value as a query parameter to the final redirect URL after signup completes successfully.
### Self-Hosted Signup Pages
When using self-hosted signup pages, your application is responsible for passing the `state` value when invoking the relevant Wristband API.
For details, see the [Provision Wristband IdP User on Signup API](https://docs.wristband.dev/reference/provisionwristbandidpuserv1) and the [Authorize External IdP User on Signup API](https://docs.wristband.dev/reference/authorizeexternalidpuseronsignupv1) reference documentation.
***
## Signup Workflow Policy
The Signup Workflow Policy allows you to customize the following behavior of the Signup workflow:
* **Verification Step:** Controls the account verification process a user must complete after signing up. Options are **Activation email workflow** or **Email verification workflow after signup**. To learn more about each option, see the [User Activation vs. Email Verification](#user-activation-vs-email-verification) section.
* Default: **Activation email workflow**
* **User Activation Strategy:** Only applicable when the **Activation email workflow** is selected. This setting controls whether the activation email contains a verification link or a one-time code.
* Default: **Send an email with a verification link**
* **Custom Redirect URL:** An optional URL to redirect users to after completing the signup workflow, instead of the application's login URL. A `{tenant_name}` placeholder can be used in the redirect URL to support tenant subdomains.
* **Block Disposable Emails: **If this toggle is enabled, users will not be able to signup using disposable or temporary emails. Enabling this feature helps to prevent users from creating spam accounts within your application. Note: this feature can only be enabled if you are on a paid Wristband plan.
* Default: **false**
{`
`}