Users

Users are a core entity central to all authentication and authorization flows, representing the individual actors interacting with your system.

The following sections detail the key aspects of user management within your application.

User Attributes

Each user has a set of descriptive attributes. Wristband natively supports the following user attributes:

Configuring Required Attributes

The user schema dictates which attributes are required and can be modified at two levels:

• Application level: Schema changes apply globally to all users across your application.
• Tenant level: Schema changes isolate their impact exclusively to users within that specific tenant.

The following user attributes can be configured as required or optional:

• Birthdate
• FamilyName
• FullName
• GivenName
• PhoneNumber
• Username

Attribute Uniqueness

Unique user attributes—such as email, username, and externalId—are scoped jointly to the tenant and identity provider. Consequently, two users can share the same email address provided they belong to distinct tenants or use different identity providers.

However, attempting to create two users with the same email address under the same tenant and identity provider will result in an error, as email addresses must be unique within that shared scope.

Conversely, two users under the same tenant can share an email address as long as they are associated with different identity providers.

Custom Metadata

In addition to native properties, you can extend Wristband user profiles with custom metadata using these two fields:

• publicMetadata: A read-accessible object exposed to end users. It typically stores public user preferences, custom profile fields, and other non-sensitive configuration data.
• restrictedMetadata: Secures custom metadata away from the end-user interface. For instance, the restrictedMetadata field can safely store a Stripe customer ID to streamline billing backend processes.

Both publicMetadata and restrictedMetadata accept a JSON object, as demonstrated in the following example:

"restrictedMetadata": {
  "stripeCustomerId": "1234",
},
"publicMetadata": {
  "favoriteFoods": ["chicken", "steak"],
  "occupation": "Software Engineer"
}

Custom Metadata Limits

The JSON objects assigned to custom metadata are subject to the following constraints:

• The max size of the JSON is 4KB.

• The max nested object depth is 3.

• The maximum number of top-level fields within an object is 15.

• Field names must match the following regex pattern: ^[a-zA-Z]([-_]?[a-zA-Z0-9]+)*$.

• Nesting arrays directly within each other is not permitted. For example, the following value is not allowed:

  Invalid Nested Lists Example

  {
    "notAllowed": [[1, 2], [3, 4]],
  }

  Whereas, the following is allowed:

  Valid Nested Lists Example

  {
    "allowed": [
      {
        "nestedList": [1, 2]
      },
      {
        "nestedList": [3, 4]
      }
    ]
  }

• Object fields are case-insensitive. If duplicate fields are provided, the last value written overwrites previous ones.

Email Verification

Email verification ensures users truly own the addresses linked to their accounts. For platforms like Wristband, this step is critical because:

• Credential Security: Temporary credentials (like one-time passwords) are delivered via email.
• Breach Prevention: Incorrect addresses can route sensitive data to unauthorized people.

To prevent unauthorized access, Wristband mandates email verification across multiple authentication flows.

Flows That Depend on Email Verification

The following authentication flows require a verified user email to function correctly:

• Password Reset: Users must verify their email before they can receive a password reset email.
• Magic Link Login: Users must verify their email before they can receive a magic link email.
• Tenant Discovery With Email Resolution: Resolving a tenant by email requires an active user in that tenant with a matching, verified email address.

Methods For Verifying a User's Email

Wristband provides multiple methods to verify a user's email address, ensuring all dependent authentication flows operate securely:

• Dedicated Email Verification Flow: Send a verification link directly to the user's email address, which they can click to verify their ownership.
• User Activation Flow: Require an email activation flow during sign-up to ensure users verify their email addresses before accessing the application.
• Change Email Flow: When users update their email, Wristband sends a verification link to the new address to confirm the change.
• Email Invitation Flows: When onboarding users via invitations, Wristband automatically marks the email as verified if the provisioned account matches the recipient's address.
• Syncing From External Identity Providers: For users provisioned through an external identity provider (IdP)—such as external sign-ups or enterprise JIT provisioning—Wristband relies on the IdP's data to determine email verification status:
  • Verified by IdP: If an IdP like Okta includes a claim confirming the email is verified, Wristband syncs the email and marks it as verified.
  • Unverified or Unknown: If the verification status is missing or the IdP flags the email as unverified, Wristband falls back to its own email verification flow.
• Manual Verification via Wristband's Dashboard: Administrators can manually update a user's email verification status directly from the Wristband dashboard.
• Programmatic Verification via Wristband's APIs: You can programmatically update a user's email verification status using Wristband's Create User API or Patch User API.

User Status

Users in Wristband have a status attribute that determines the state the user is in and what actions they are allowed to take in that state. The following table lists all possible user statuses:

Onboarding Users

Wristband supports multiple user onboarding methods to fit your application's architecture. Learn about each approach below:

Tenant Signup

The Tenant Signup Flow lets users self-register within a specific tenant.

• How it works: Users sign up at https://<tenant_vanity_domain>/signup. After entering their required attributes and credentials, they are provisioned and can log in immediately.
• Tenant control: You can enable this feature on a per-tenant basis.
• Domain restrictions: To restrict registration to specific company emails, add authorized domains to the tenant's allowedSignupEmailDomains list.

For more details, check out the Signup Workflow documentation.

Application Signup

The Application Signup Flow works like the Tenant Signup Flow, but it automatically creates a brand-new tenant for the user.

The process: Users sign up at https://<application_vanity_domain>/signup.

Requirements: Users must provide a unique tenant name along with their personal attributes and credentials.

Configuration: You can disable this flow if you prefer to handle tenant creation manually.

To learn more, see the Signup Workflow documentation.

New User Invitation

The New User Invitation Flow allows administrators to invite individuals to join a specific tenant using an email or a direct link.

• Provisioning: Once the invitee accepts, Wristband provisions the user under that tenant.
• Role Assignment: Administrators can pre-assign roles during invitation creation, which the system automatically applies to the user profile upon activation.

To learn more, see the New User Invitation Workflow documentation.

Manual Provisioning via Wristband's Dashboard

Administrators can manually provision users for a specific tenant via the Wristband dashboard. Initially, these users have a status of PROVISIONED, an unverified email, and no password, which blocks them from logging in.

To activate the user, choose one of two onboarding paths:

• Existing User Invitation Email: Sending this email prompts the user to accept, which automatically changes their status to ACTIVE, verifies their email, and lets them set a password.
• Manual Admin Activation: An administrator can manually change the status to ACTIVE and verify their email. However, because admins cannot set passwords directly, the user must then complete the Password Reset Flow to log in.

To learn more, see the Existing User Invitation Workflow documentation.

Just-in-Time (JIT) Provisioning

Just-in-Time (JIT) provisioning automatically creates user accounts during their first successful authentication through an enterprise identity provider (IdP).

• Supported IdPs: Works seamlessly with providers like Okta or Microsoft Entra ID.
• Key Benefit: Streamlines onboarding by completely eliminating the need for manual user creation.

To learn more,see the JIT Provisioning documentation.

Programmatic Provisioning via Wristband's APIs

Provision users programmatically using Wristband's APIs to handle bulk imports or embed user creation directly into your application's workflows.

To get started with API provisioning, refer to the Wristband Create User API.

Assigning Roles to Users

Assign roles to users to enforce authorization and access control within your application. Wristband supports the following role assignment methods:

• Role Assignment Policies: Role assignment policies automatically assign roles to users for these specific use cases:

  • Signup: Specify a list of default roles to automatically assign to users when they complete the sign-up flow.
  • Enterprise Identity Provider Role Mapping: When enterprise identity providers (IdPs) have role mapping enabled, you can specify default roles to assign during sign-up or login. These default roles will be applied when Wristband cannot derive roles dynamically from the user claims provided by the IdP.

• Manually via the Wristband Dashboard: Administrators can manually assign roles via the Wristband dashboard. Additionally, when sending user invitations, admins can pre-select the roles that will automatically apply once the user accepts the invite.

• Enterprise Identity Provider Role Mappings: When configuring an enterprise IdP, you can create role mappings to automatically assign Wristband roles based on synced user claims. For example, you can map an external identity provider group to a specific Wristband role.

  To learn more, see the Role Mappings documentation.

• Programmatically via Wristband's APIs: Use the following API endpoints to manage user role assignments programmatically:

  • Assign Roles To User API
  • Unassign Roles From User API
  • Update User Roles Assignments API

Managing Users With Wristband's Dashboard

The Wristband dashboard provides a comprehensive set of tools for managing your application's users. The sections below highlight the dashboard's core user management features.

Adding Users

Users can be manually added to a tenant by clicking "Users" from the left navigation menu and then clicking the "Add User" button.

After clicking the "Add User" button, a modal will appear, prompting you to provide the required information to create the user.

When users are provisioned through the create user modal, they initially have a status of PROVISIONED, their email is unverified, and they don't have a password. As such, users in this state won't be able to authenticate successfully using Wristband. To get the user into an active state, you can optionally send an Existing User Invitation Email to the user. When the user clicks the link inside the Existing User Invitation Email, the following actions will be performed:

• The user will be prompted to set a new password (if passwords are enabled as a login factor).
• The user's status will be set to ACTIVE.
• The user's email will be marked as verified.

If you choose not to send an Existing User Invitation Email, you can also manually set the user's status to ACTIVE and mark their email as verified. You won't be able to set the user's password directly, but the user can update it themselves by going through the Password Reset Flow once their status has been set to ACTIVE and their email has been verified.

Editing Existing Users

You can edit a user by clicking "Users" from the left navigation menu and then clicking the user you want to edit from the users table.

On the user details page, you can freely modify any of the user's profile attributes.

Updating Custom Metadata

In addition to updating the user's standard fields, you can also update the custom metadata associated with a user. The public metadata and restricted metadata fields can accept any valid JSON object, as long as they abide by the limits specified in the Custom Metadata Limits section.

Verifying the User's Email Address

If a user's email is not verified, on the user details page, you'll see a "Verify Email" button.

If you click the "Verify Email" button, you'll be presented with the following options for verifying the user's email:

• Immediate Verification: If this option is selected, the user's email will be immediately marked as verified without sending a verification email.
• Send a Verification Email: If this option is selected, then a verification email will be sent to the user's current email address. The user will then need to click the link in the email to complete the verification process. Note, this option can only be used if the user has an ACTIVE status.

Changing a User's Email Address

On the user details page, you can also change a user's email address by clicking the "Change Email" button.

When you click the "Change Email" button, you'll be prompted to enter the user's new email address and select how the new email address should be verified. Below is a list of the different methods that can be used to verify the user's email:

• Skip Verification: If this option is selected, the user's email will be changed to the new address, but it will be marked as unverified.
• Immediate Verification: If this option is selected, the user's email address will be updated to the new one, and it will be immediately marked as verified.
• Send a Confirmation Email: If this option is selected, the user will receive a confirmation email at their new address. The email address will not be updated until the user clicks the link in that email. Once clicked, the user's email attribute will be updated and marked as verified. Note, this option can only be used if the user has an ACTIVE status.

Assigning Roles

To assign roles to the user, scroll down to the "Roles" section. There, you'll see a multi-select dropdown that can be used to modify the roles assigned to a user.

Managing the User's Status

On the user details page, you can also invoke certain operations depending on the user's status. In the sections below, we'll cover all the operations that can be performed on a user based on their current state.

Operations For Users In a Provisioned State

• Send an Invitation Email: This will trigger an Existing User Invitation Email to be sent to the user's email address.
• Activate User: Sets the user's status to ACTIVE.
• Deactivate User: Sets the user's status to INACTIVE.

Operations For Users In a Pending Signup Activation State

• Send Activation Email: Resends the User Activation Email to the user. This can be useful for cases where the user didn't complete the activation step and no longer has a valid activation email.
• Activate User: Sets the user's status to ACTIVE.
• Deactivate User: Sets the user's status to INACTIVE.

Operations For Users In a Pending Invite Activation State

• Send Activation Email: Resends the User Activation Email to the user. This can be useful for cases where the user didn't complete the activation step and no longer has a valid activation email.
• Activate User: Sets the user's status to ACTIVE.
• Deactivate User: Sets the user's status to INACTIVE.

Operations For Users In an Active State

• Deactivate User: Sets the user's status to INACTIVE.

Operations For Users In an Inactive State

• Send an Invitation Email: This will trigger an Existing User Invitation Email to be sent to the user's email address.
• Activate User: Sets the user's status to ACTIVE.

Viewing the User's Active Refresh Tokens

To view a user's active refresh tokens, scroll to the Active Refresh Tokens section on the user details page.From this section, you can manage the tokens using these actions:

• Trash can icon: Revoke an individual refresh token.
• Revoke Tokens button: Revoke all refresh tokens associated with the user.

Viewing the User's Active Auth Sessions

To view a user's active sessions, scroll to the Active Auth Sessions section on the user details page.From this section, you can manage sessions using these actions:

• Trash can icon: Delete an individual auth session.
• Delete Sessions button: Delete all auth sessions associated with the user.

Deleting the User

To delete the user, click the Delete button at the bottom of the user details page.

Inviting New Users

To invite new users to a tenant, click Users in the left navigation menu and scroll to the New User Invitations section.

Under the "New User Invitations" section, you'll see the following two options for inviting users:

1. Emails: Use this option to send an invitation email to a new user. When sending from the Application View, you must specify:

   • Tenant: The specific workspace the user will join (required).
   • Roles: The permissions assigned to the user upon joining (optional).

2. Generated Links: Use this option to create a single-use invitation link to share via text channels (like Slack). Link expiration is controlled by your New User Invitation Workflow Policy. To generate the link, you must provide:

   Invitee Name: Used to identify the link (required).

   Tenant: The specific workspace they will join, required only if generating from the Application View.

   Roles: The permissions assigned to the user upon joining (optional).

Managing Active Invitations

The dashboard displays all active email and link invitations. From here, you can manage them based on their type:

• Email invitations: Resend the invitation email.
• Invitation links: Regenerate the link.
• Both types: Cancel the invitation.

Updating the User Schema

To configure required user fields, click User Schema in the left navigation menu. The scope of your changes depends on your current view:

1. Application View: Changes apply to all users across the entire application.
2. Tenant View: Changes apply only to users in that specific tenant.

Note: You must turn on the User Schema Tenant Override Toggle for these changes to take effect.