TWtwilio
VerifyV2NewFactor

Create a new Factor for the Entity

Changed on

Create a new Factor for the Entity

post/v2/Services/{ServiceSid}/Entities/{Identity}/Factors

Request

  • Base URL
    https://verify.twilio.com
  • URL
    https://verify.twilio.com/v2/Services/{ServiceSid}/Entities/{Identity}/Factors
  • Auth
    HTTP basic

Path parameters

ServiceSidstring required

The unique SID identifier of the Service.

Identitystring required

Customer unique identity for the Entity owner of the Factor. This identifier should be immutable, not PII, length between 8 and 64 characters, and generated by your external system, such as your user's UUID, GUID, or SID. It can only contain dash (-) separated alphanumeric characters.

Request body application/x-www-form-urlencoded

FriendlyNamestring required

The friendly name of this Factor. This can be any string up to 64 characters, meant for humans to distinguish between Factors. For factor_type push, this could be a device name. For factor_type totp, this value is used as the “account name” in constructing the binding.uri property. At the same time, we recommend avoiding providing PII.

FactorType'push' | 'totp' | 'passkeys' required

The Type of this Factor. Currently push and totp are supported.

Binding.Algstring

The algorithm used when factor_type is push. Algorithm supported: ES256

Binding.PublicKeystring

The Ecdsa public key in PKIX, ASN.1 DER format encoded in Base64.

Required when factor_type is push

Config.AppIdstring

The ID that uniquely identifies your app in the Google or Apple store, such as com.example.myapp. It can be up to 100 characters long.

Required when factor_type is push.

Config.NotificationPlatform'apn' | 'fcm' | 'none'
Config.NotificationTokenstring

For APN, the device token. For FCM, the registration token. It is used to send the push notifications. Must be between 32 and 255 characters long.

Required when factor_type is push.

Config.SdkVersionstring

The Verify Push SDK version used to configure the factor

Required when factor_type is push

Binding.Secretstring

The shared secret for TOTP factors encoded in Base32. This can be provided when creating the Factor, otherwise it will be generated.

Used when factor_type is totp

Config.TimeStepinteger

Defines how often, in seconds, are TOTP codes generated. i.e, a new TOTP code is generated every time_step seconds. Must be between 20 and 60 seconds, inclusive. The default value is defined at the service level in the property totp.time_step. Defaults to 30 seconds if not configured.

Used when factor_type is totp

Config.Skewinteger

The number of time-steps, past and future, that are valid for validation of TOTP codes. Must be between 0 and 2, inclusive. The default value is defined at the service level in the property totp.skew. If not configured defaults to 1.

Used when factor_type is totp

Config.CodeLengthinteger

Number of digits for generated TOTP codes. Must be between 3 and 8, inclusive. The default value is defined at the service level in the property totp.code_length. If not configured defaults to 6.

Used when factor_type is totp

Config.Alg'sha1' | 'sha256' | 'sha512'
Metadataunknown

Response

Created

sidstring nullable

A 34 character string that uniquely identifies this Factor.

account_sidstring nullable

The unique SID identifier of the Account.

service_sidstring nullable

The unique SID identifier of the Service.

entity_sidstring nullable

The unique SID identifier of the Entity.

identitystring nullable

Customer unique identity for the Entity owner of the Factor. This identifier should be immutable, not PII, length between 8 and 64 characters, and generated by your external system, such as your user's UUID, GUID, or SID. It can only contain dash (-) separated alphanumeric characters.

bindingunknown
optionsunknown
date_createdstring date-time nullable

The date that this Factor was created, given in ISO 8601 format.

date_updatedstring date-time nullable

The date that this Factor was updated, given in ISO 8601 format.

friendly_namestring nullable

The friendly name of this Factor. This can be any string up to 64 characters, meant for humans to distinguish between Factors. For factor_type push, this could be a device name. For factor_type totp, this value is used as the “account name” in constructing the binding.uri property. At the same time, we recommend avoiding providing PII.

status'unverified' | 'verified'

The Status of this Factor. One of unverified or verified.

factor_type'push' | 'totp' | 'passkeys'

The Type of this Factor. Currently push and totp are supported.

configunknown
metadataunknown
urlstring uri nullable

The URL of this resource.

Changes

  • v23fd4376faab5Revision changes
    • warning

      added the new passkeys enum value to the response property for the response status

    • info

      added the new passkeys enum value to the request property

    • info

      added the optional property to the response with the status

  • v21548692e6804Revision changes
    • breaking

      the response's property type changed from object to no type for status

    • breaking

      the response's property type changed from object to no type for status

    • breaking

      the response's property type changed from object to no type for status

    • info

      the request property type was generalized from object to no type