The operation POST /environments/{{envID}}/users/{{userID}}/devices adds a new SMS MFA method to the specified user resource.

The status parameter is optional. Use cases:

  1. If the actor makes the request on behalf of another user, the value assigned to status can be one of:
  2. If the actor making the request is the same user for whom the device is created, the status can only be ACTIVATION_REQUIRED (default, if not provided). Thus in this case, a user is required to activate the device before performing its first authentication.

If the status is ACTIVATION_REQUIRED, you can use the notification property during device creation to create a custom device pairing notification. This is only applicable with SMS, Voice and Email devices. This property is not returned with GET operations and cannot be used with PUT operations. For more information, see Custom device pairing notification with device creation.

A valid phone number string must be provided in international format (includes a leading + character), for example, +14155552671.

Always include the country code in the value you provide for the phone parameter. Phone formats across the globe are constantly expanding and changing. If the country code is not included, issues might occur with message delivery.

The following sample shows acceptable valid phone attribute formatting for the same number:

+1.5125201234
+15125201234
+1.512.520.1234
+1 (512) 520-1234

Prerequisites

Property Type Required?
type String Required
phone String Required
policy.id String Required
notification String Optional
testMode Boolean Optional
block.status String Optional
block.blockedAt Date Optional
lock.status String Optional
lock.expiresAt Date Optional
policy.id String Optional
policy.type String Optional
nickname String Optional

See the Device properties data models for full property descriptions.