Skip to main content

SignUpFuture object

The SignUpFuture object holds the state of the current sign-up attempt and provides methods to drive custom sign-up flows, including email/phone verification, password, SSO, ticket-based, and Web3-based account creation.

Example

See the custom flow guides for comprehensive examples of using the SignUpFuture object to build custom user interfaces with the Clerk API.

Properties

  • Name
    abandonAt
    Type
    null | number
    Description

    The epoch numerical time when the sign-up was abandoned by the user.

  • Name
    createdSessionId
    Type
    null | string
    Description

    The identifier of the newly-created session. This attribute is populated only when the sign-up is complete.

  • Name
    createdUserId
    Type
    null | string
    Description

    The identifier of the newly-created user. This attribute is populated only when the sign-up is complete.

  • Name
    emailAddress
    Type
    null | string
    Description

    The emailAddress supplied to the current sign-up. Only supported if email address is enabled in the instance settings.

  • Name
    existingSession?
    Type
    { sessionId: string; }
    Description

    Indicates that the sign-up was not able to create a new session because the identifier already exists in an existing session.

  • Name
    existingSession.sessionId
    Type
    string
    Description

    The ID of the existing session.

  • Name
    firstName
    Type
    null | string
    Description

    The firstName supplied to the current sign-up. Only supported if First and last name is enabled in the instance settings.

  • Name
    hasPassword
    Type
    boolean
    Description

    The value of this attribute is true if a password was supplied to the current sign-up. Only supported if password is enabled in the instance settings.

  • Name
    id?
    Type
    string
    Description

    The unique identifier of the current sign-up.

  • Name
    isTransferable
    Type
    boolean
    Description

    Indicates that there is a matching user for provided identifier, and that the sign-up can be transferred to a sign-in.

  • Name
    lastName
    Type
    null | string
    Description

    The lastName supplied to the current sign-up. Only supported if First and last name is enabled in the instance settings.

  • Name
    legalAcceptedAt
    Type
    null | number
    Description

    The epoch numerical time when the user agreed to the legal compliance documents.

  • Name
    locale
    Type
    null | string
    Description

    The locale of the user in BCP 47 format (e.g., "en-US", "fr-FR"), or null if not set.

  • Name
    missingFields
    Type
    (OAuthStrategy | "password" | "email_address" | "phone_number" | "username" | "first_name" | "last_name" | "web3_wallet" | "enterprise_sso" | "legal_accepted" | "email_address_or_phone_number")[]
    Description

    An array of all the fields whose values are not supplied yet but they are mandatory in order for a sign-up to be marked as complete.

  • Name
    optionalFields
    Type
    (OAuthStrategy | "password" | "email_address" | "phone_number" | "username" | "first_name" | "last_name" | "web3_wallet" | "enterprise_sso" | "legal_accepted" | "email_address_or_phone_number")[]
    Description

    An array of all the fields that can be supplied to the sign-up, but their absence does not prevent the sign-up from being marked as complete.

  • Name
    phoneNumber
    Type
    null | string
    Description

    The phoneNumber supplied to the current sign-up in E.164 format. Only supported if phone number is enabled in the instance settings.

  • Name
    requiredFields
    Type
    (OAuthStrategy | "password" | "email_address" | "phone_number" | "username" | "first_name" | "last_name" | "web3_wallet" | "enterprise_sso" | "legal_accepted" | "email_address_or_phone_number")[]
    Description

    An array of all the required fields that need to be supplied and verified in order for this sign-up to be marked as complete and converted into a user.

  • Name
    status
    Type
    "complete" | "abandoned" | "missing_requirements"
    Description

    The status of the current sign-up.

  • Name
    unsafeMetadata
    Type
    SignUpUnsafeMetadata
    Description

    Metadata that can be read and set from the frontend. Once the sign-up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign-up and will automatically be attached to the created User object.

  • Name
    unverifiedFields
    Type
    (OAuthStrategy | "email_address" | "phone_number" | "username" | "web3_wallet" | "enterprise_sso" | "email_address_or_phone_number")[]
    Description

    An array of all the fields whose values have been supplied, but they need additional verification in order for them to be accepted. Examples of such fields are email_address and phone_number.

  • Name
    username
    Type
    null | string
    Description

    The username supplied to the current sign-up. Only supported if username is enabled in the instance settings.

  • Name
    web3Wallet
    Type
    null | string
    Description

    The Web3 wallet address supplied to the current sign-up, made up of 0x + 40 hexadecimal characters. Only supported if Web3 authentication is enabled in the instance settings.

Methods

create()

Creates a new SignUp instance initialized with the provided parameters. The instance maintains the sign-up lifecycle state through its status property, which updates as the authentication flow progresses. Will also deactivate any existing sign-up process the client may already have in progress. Once the sign-up process is complete, call the signUp.finalize() method to set the newly created session as the active session.

What you must pass to params depends on which sign-up options you have enabled in your app's settings in the Clerk Dashboard.

You can complete the sign-up process in one step if you supply the required fields to create(). Otherwise, Clerk's sign-up process provides great flexibility and allows users to easily create multi-step sign-up flows.

Important

The signUp.create() method is intended for advanced use cases. For most use cases, prefer the use of the factor-specific methods such as signUp.password(), signUp.sso(), etc.

function create(params: SignUpFutureCreateParams): Promise<{ error: null | ClerkError }>

SignUpFutureCreateParams

  • Name
    emailAddress?
    Type
    string
    Description

    The user's email address. Only supported if Email address is enabled in the instance settings. Keep in mind that the email address requires an extra verification process.

  • Name
    firstName?
    Type
    string
    Description

    The user's first name. Only supported if First and last name is enabled in the instance settings.

  • Name
    lastName?
    Type
    string
    Description

    The user's last name. Only supported if First and last name is enabled in the instance settings.

  • Name
    legalAccepted?
    Type
    boolean
    Description

    Indicates whether the user has agreed to the legal compliance documents.

  • Name
    locale?
    Type
    string
    Description

    The locale to assign to the user in BCP 47 format (e.g., "en-US", "fr-FR"). If omitted, defaults to the browser's locale.

  • Name
    password?
    Type
    string
    Description

    The user's password. Password must be enabled in the instance settings.

  • Name
    phoneNumber?
    Type
    string
    Description

    The user's phone number in E.164 format. Only supported if phone number is enabled in the instance settings. Keep in mind that the phone number requires an extra verification process.

  • Name
    strategy?
    Type
    OAuthStrategy | "phone_code" | "enterprise_sso" | "ticket" | "google_one_tap" | "oauth_token_apple"
    Description

    The strategy to use for the sign-up. The following strategies are supported:

    • 'oauth_<provider>': The user will be authenticated with their social connection account. See a list of supported values for <provider>.
    • 'enterprise_sso': The user will be authenticated either through SAML or OIDC depending on the configuration of their enterprise SSO account.
    • 'ticket': The user will be authenticated via the ticket or token generated from the Backend API.
    • 'google_one_tap': The user will be authenticated with the Google One Tap UI. It's recommended to use authenticateWithGoogleOneTap() instead, as it will also set the user's current session as active for you.
    • 'oauth_token_apple': The user will be authenticated using a native Sign in with Apple identity token.
    • 'phone_code': The user will receive a one-time code via SMS to verify their phone number.
  • Name
    ticket?
    Type
    string
    Description

    Required if strategy is set to 'ticket'. The ticket or token generated from the Backend API.

  • Name
    transfer?
    Type
    boolean
    Description

    When set to true, the SignUp will attempt to retrieve information from the active SignIn instance and use it to complete the sign-up process. This is useful when you want to seamlessly transition a user from a sign-in attempt to a sign-up attempt.

  • Name
    unsafeMetadata?
    Type
    SignUpUnsafeMetadata
    Description

    Metadata that can be read and set from the frontend. Once the sign-up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign-up and will automatically be attached to the created User object.

  • Name
    username?
    Type
    string
    Description

    The user's username. Only supported if username is enabled in the instance settings.

  • Name
    web3Wallet?
    Type
    string
    Description

    The Web3 wallet address, made up of 0x + 40 hexadecimal characters. Only supported if Web3 authentication is enabled in the instance settings.

finalize()

Converts a sign-up with status === 'complete' into an active session. Will cause anything observing the session state (such as the useUser() hook) to update automatically.

function finalize(params?: SignUpFutureFinalizeParams): Promise<{ error: null | ClerkError }>

SignUpFutureFinalizeParams

  • Name
    navigate?
    Type
    SetActiveNavigate
    Description

    A custom navigation function to be called just before the session and/or Organization is set. When provided, it takes precedence over the redirectUrl parameter for navigation. The callback receives a decorateUrl function that should be used to wrap destination URLs. This enables Safari ITP cookie refresh when needed. The decorated URL may be an external URL (starting with https://) that requires window.location.href instead of client-side navigation. See the section on using the navigate() parameter for more details.

password()

Performs a password-based sign-up.

function password(params: SignUpFuturePasswordParams): Promise<{ error: null | ClerkError }>

SignUpFuturePasswordParams

  • Name
    emailAddress
    Type
    string
    Description

    The user's email address. Only supported if Email address is enabled in the instance settings. Keep in mind that the email address requires an extra verification process.

  • Name
    firstName?
    Type
    string
    Description

    The user's first name. Only supported if First and last name is enabled in the instance settings.

  • Name
    lastName?
    Type
    string
    Description

    The user's last name. Only supported if First and last name is enabled in the instance settings.

  • Name
    legalAccepted?
    Type
    boolean
    Description

    Indicates whether the user has agreed to the legal compliance documents.

  • Name
    locale?
    Type
    string
    Description

    The locale to assign to the user in BCP 47 format (e.g., "en-US", "fr-FR"). If omitted, defaults to the browser's locale.

  • Name
    password
    Type
    string
    Description

    The user's password. Password must be enabled in the instance settings.

  • Name
    phoneNumber?
    Type
    string
    Description

    The user's phone number in E.164 format. Only supported if phone number is enabled in the instance settings. Keep in mind that the phone number requires an extra verification process.

  • Name
    unsafeMetadata?
    Type
    SignUpUnsafeMetadata
    Description

    Metadata that can be read and set from the frontend. Once the sign-up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign-up and will automatically be attached to the created User object.

  • Name
    username?
    Type
    string
    Description

    The user's username. Only supported if username is enabled in the instance settings.

reset()

Resets the current sign-up attempt by clearing all local state back to null. This is useful when you want to allow users to go back to the beginning of the sign-up flow (e.g., to change their email address during verification).

Unlike other methods, reset() does not trigger the fetchStatus to change to 'fetching' and does not make any API calls - it only clears local state.

function reset(): Promise<{ error: null | ClerkError }>

sso()

Performs an SSO-based sign-up (Social/OAuth or Enterprise).

function sso(params: SignUpFutureSSOParams): Promise<{ error: null | ClerkError }>

SignUpFutureSSOParams

  • Name
    emailAddress?
    Type
    string
    Description

    The email address to use for targeting an enterprise connection at sign-up.

  • Name
    enterpriseConnectionId?
    Type
    string
    Description

    The identifier of the enterprise connection to target when using the enterprise_sso strategy.

  • Name
    firstName?
    Type
    string
    Description

    The user's first name. Only supported if First and last name is enabled in the instance settings.

  • Name
    lastName?
    Type
    string
    Description

    The user's last name. Only supported if First and last name is enabled in the instance settings.

  • Name
    legalAccepted?
    Type
    boolean
    Description

    Indicates whether the user has agreed to the legal compliance documents.

  • Name
    locale?
    Type
    string
    Description

    The locale to assign to the user in BCP 47 format (e.g., "en-US", "fr-FR"). If omitted, defaults to the browser's locale.

  • Name
    oidcPrompt?
    Type
    string
    Description

    The value to pass to the OIDC prompt parameter in the generated OAuth redirect URL.

  • Name
    popup?
    Type
    Window
    Description

    If provided, a Window to use for the OAuth flow. Useful in instances where you cannot navigate to an OAuth provider.

  • Name
    redirectCallbackUrl
    Type
    string
    Description

    The URL or path to navigate to if a session was not created, and needs additional information.

  • Name
    redirectUrl
    Type
    string
    Description

    The URL or path to navigate to after the OAuth or SAML flow completes. Can be provided as a relative URL (such as /dashboard), in which case it will be prefixed with the base URL of the current page.

  • Name
    strategy
    Type
    string
    Description

    The strategy to use for authentication. Either OAuthStrategy or EnterpriseSSOStrategy.

  • Name
    unsafeMetadata?
    Type
    SignUpUnsafeMetadata
    Description

    Metadata that can be read and set from the frontend. Once the sign-up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign-up and will automatically be attached to the created User object.

ticket()

Performs a ticket-based sign-up.

function ticket(params?: SignUpFutureTicketParams): Promise<{ error: null | ClerkError }>

SignUpFutureTicketParams

  • Name
    firstName?
    Type
    string
    Description

    The user's first name. Only supported if First and last name is enabled in the instance settings.

  • Name
    lastName?
    Type
    string
    Description

    The user's last name. Only supported if First and last name is enabled in the instance settings.

  • Name
    legalAccepted?
    Type
    boolean
    Description

    Indicates whether the user has agreed to the legal compliance documents.

  • Name
    locale?
    Type
    string
    Description

    The locale to assign to the user in BCP 47 format (e.g., "en-US", "fr-FR"). If omitted, defaults to the browser's locale.

  • Name
    ticket
    Type
    string
    Description

    Required if strategy is set to 'ticket'. The ticket or token generated from the Backend API.

  • Name
    unsafeMetadata?
    Type
    SignUpUnsafeMetadata
    Description

    Metadata that can be read and set from the frontend. Once the sign-up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign-up and will automatically be attached to the created User object.

update()

Updates the current SignUpFuture instance with the provided parameters.

function update(params: SignUpFutureUpdateParams): Promise<{ error: null | ClerkError }>

SignUpFutureUpdateParams

  • Name
    emailAddress?
    Type
    string
    Description

    The user's email address. Only supported if Email address is enabled in the instance settings. Keep in mind that the email address requires an extra verification process.

  • Name
    firstName?
    Type
    string
    Description

    The user's first name. Only supported if First and last name is enabled in the instance settings.

  • Name
    lastName?
    Type
    string
    Description

    The user's last name. Only supported if First and last name is enabled in the instance settings.

  • Name
    legalAccepted?
    Type
    boolean
    Description

    Indicates whether the user has agreed to the legal compliance documents.

  • Name
    locale?
    Type
    string
    Description

    The locale to assign to the user in BCP 47 format (e.g., "en-US", "fr-FR"). If omitted, defaults to the browser's locale.

  • Name
    phoneNumber?
    Type
    string
    Description

    The user's phone number in E.164 format. Only supported if phone number is enabled in the instance settings. Keep in mind that the phone number requires an extra verification process.

  • Name
    unsafeMetadata?
    Type
    SignUpUnsafeMetadata
    Description

    Metadata that can be read and set from the frontend. Once the sign-up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign-up and will automatically be attached to the created User object.

  • Name
    username?
    Type
    string
    Description

    The user's username. Only supported if username is enabled in the instance settings.

verifications

An object that contains information about all available verification strategies.

  • Name
    emailAddress
    Type
    SignUpVerificationResource
    Description

    Holds information about the email address verification.

  • Name
    emailLinkVerification
    Type
    null | { createdSessionId: string; status: "expired" | "failed" | "verified" | "client_mismatch"; verifiedFromTheSameClient: boolean; }
    Description

    The verification status for email link flows.

    • status: The verification status.
    • createdSessionId: The ID of the session that was created upon successful verification.
    • verifiedFromTheSameClient: Whether the verification was from the same client (browser) that initiated the email link flow.
  • Name
    externalAccount
    Type
    VerificationResource
    Description

    Holds information about the external account verification.

  • Name
    phoneNumber
    Type
    SignUpVerificationResource
    Description

    Holds information about the phone number verification.

  • Name
    web3Wallet
    Type
    VerificationResource
    Description

    Holds information about the Web3 wallet verification.

verifications.sendEmailCode()

Sends an email code to verify an email address.

function sendEmailCode(): Promise<{ error: null | ClerkError }>

verifications.verifyEmailCode()

Verifies a code sent with the verifications.sendEmailCode() method.

function verifyEmailCode(params: SignUpFutureEmailCodeVerifyParams): Promise<{ error: null | ClerkError }>

SignUpFutureEmailCodeVerifyParams

  • Name
    code
    Type
    string
    Description

    The code that was sent to the user.

Sends an email link to verify an email address.

function sendEmailLink(params: SignUpFutureEmailLinkSendParams): Promise<{ error: null | ClerkError }>
  • Name
    verificationUrl
    Type
    string
    Description

    The full URL that the user will be redirected to when they visit the email link.

Will wait for email link verification to complete or expire after calling verifications.sendEmailLink().

function waitForEmailLinkVerification(): Promise<{ error: null | ClerkError }>

verifications.sendPhoneCode()

Sends a phone code to verify a phone number.

function sendPhoneCode(params?: SignUpFuturePhoneCodeSendParams): Promise<{ error: null | ClerkError }>

SignUpFuturePhoneCodeSendParams

  • Name
    channel?
    Type
    "sms" | "whatsapp"
    Description

    The mechanism to use to send the code to the provided phone number. Defaults to 'sms'.

verifications.verifyPhoneCode()

Verifies a code sent with the verifications.sendPhoneCode() method.

function verifyPhoneCode(params: SignUpFuturePhoneCodeVerifyParams): Promise<{ error: null | ClerkError }>

SignUpFuturePhoneCodeVerifyParams

  • Name
    code
    Type
    string
    Description

    The code that was sent to the user.

web3()

Performs a Web3-based sign-up.

function web3(params: SignUpFutureWeb3Params): Promise<{ error: null | ClerkError }>

SignUpFutureWeb3Params

  • Name
    firstName?
    Type
    string
    Description

    The user's first name. Only supported if First and last name is enabled in the instance settings.

  • Name
    lastName?
    Type
    string
    Description

    The user's last name. Only supported if First and last name is enabled in the instance settings.

  • Name
    legalAccepted?
    Type
    boolean
    Description

    Indicates whether the user has agreed to the legal compliance documents.

  • Name
    locale?
    Type
    string
    Description

    The locale to assign to the user in BCP 47 format (e.g., "en-US", "fr-FR"). If omitted, defaults to the browser's locale.

  • Name
    strategy
    Type
    "web3_metamask_signature" | "web3_base_signature" | "web3_coinbase_wallet_signature" | "web3_okx_wallet_signature" | "web3_solana_signature"
    Description

    The verification strategy to validate the user's sign-up request.

  • Name
    unsafeMetadata?
    Type
    SignUpUnsafeMetadata
    Description

    Metadata that can be read and set from the frontend. Once the sign-up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign-up and will automatically be attached to the created User object.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub