Skip to main content
Docs

PhoneNumber

The PhoneNumber object describes a phone number. Phone numbers can be used as a proof of identification for users, or simply as a means of contacting users.

Phone numbers must be verified to ensure that they can be assigned to their rightful owners. The PhoneNumber object holds all the necessary state around the verification process.

  • The verification process always starts with the prepareVerification() method, which will send a one-time verification code via an SMS message.
  • The second and final step involves an attempt to complete the verification by calling the attemptVerification() method, passing the one-time code as a parameter.

Finally, phone numbers can be used as part of multi-factor authentication. During sign in, users can opt in to an extra verification step where they will receive an SMS message with a one-time code. This code must be entered to complete the sign in process.

Properties

  • Name
    id
    Type
    string
    Description

    The unique identifier for this phone number.

  • Name
    phoneNumber
    Type
    string
    Description

    The value of this phone number, in E.164 format.

  • Name
    reservedForSecondFactor
    Type
    boolean
    Description

    Set to true if this phone number is reserved for multi-factor authentication (2FA). Set to false otherwise.

  • Name
    defaultSecondFactor
    Type
    boolean
    Description

    Set to true if this phone number is the default second factor. Set to false otherwise. A user must have exactly one default second factor, if multi-factor authentication (2FA) is enabled.

  • Name
    verification
    Type
    Verification
    Description

    An object holding information on the verification of this phone number.

  • Name
    linkedTo
    Type
    Array<{id: string, type: string}>
    Description

    An object containing information about any other identification that might be linked to this phone number.

  • Name
    backupCodes
    Type
    string[] | undefined
    Description

    A list of backup codes in case of lost phone number access.

Methods

create()

Creates a new phone number for the current user.

function create(): Promise<PhoneNumber>

destroy()

Deletes this phone number.

function destroy(): Promise<void>

toString()

Returns the in E.164 format which includes the country code and the phone number.. Can also be accessed via the PhoneNumber.phoneNumber attribute.

function toString(): string

prepareVerification()

Kick off the verification process for this phone number. An SMS message with a one-time code will be sent to the phone number value.

function prepareVerification(): Promise<PhoneNumber>

attemptVerification()

Attempts to verify this phone number, passing the one-time code that was sent as an SMS message. The code will be sent when calling the PhoneNumber.prepareVerification() method.

function attemptVerification(params: AttemptPhoneNumberVerificationParams): Promise<PhoneNumber>

AttemptPhoneNumberVerificationParams

  • Name
    code
    Type
    string
    Description

    The one-time code that was sent to the user's phone number when prepareVerification was called.

makeDefaultSecondFactor()

Marks this phone number as the default second factor for multi-factor authentication(2FA). A user can have exactly one default second factor.

function makeDefaultSecondFactor(): Promise<PhoneNumber>

setReservedForSecondFactor()

Marks this phone number as reserved for multi-factor authentication (2FA) or not.

function setReservedForSecondFactor(params: SetReservedForSecondFactorParams): Promise<PhoneNumber>

SetReservedForSecondFactorParams

  • Name
    reserved
    Type
    boolean
    Description

    Pass true to mark this phone number as reserved for 2FA, or false to disable 2FA for this phone number.

Feedback

What did you think of this content?
GitHubEdit on GitHub

Last updated on