The Factor
resource is currently used by Verify Push and Verify TOTP features. It represents a verification factor/channel. When the factor_type
is push
, it contains the public key for a single registered device and metadata. When the factor_type
is totp
, it contains the seed used to generate TOTP codes and metadata. Some Factor
properties apply to all factor_types
and others do not. A single Entity
links to multiple Factors
and a single Factor
links to multiple Challenges
.
For security reasons the binding
property is ONLY returned upon creation, and is never returned afterward.
identity
type: stringCustomer 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.
binding
type: objectContains the factor_type
specific secret and metadata.
For push, this is binding.public_key
and binding.alg
.
For totp, this is binding.secret
and binding.uri
. The binding.uri
property is generated following the google authenticator key URI format, and Factor.friendly_name
is used for the “accountname” value and Service.friendly_name
or Service.totp.issuer
is used for the issuer
value.
The Binding property is ONLY returned upon Factor creation.
friendly_name
type: stringThe 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
type: enum<string>The Status of this Factor. One of unverified
or verified
.
unverified
verified
factor_type
type: enum<string>The Type of this Factor. Currently push
and totp
are supported.
push
totp
metadata
type: objectCustom metadata associated with the factor. This is added by the Device/SDK directly to allow for the inclusion of device information. It must be a stringified JSON with only strings values eg. {"os": "Android"}
. Can be up to 1024 characters in length.
POST
_10https://verify.twilio.com/v2/Services/{ServiceSid}/Entities/{Identity}/Factors
Entity
with the
{Identity}
doesn't exist, it will be created automatically. You do not need to separately create a new Entity before making this request.
Parameters
Identity
type: stringCustomer 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.
FriendlyName
type: stringRequiredThe 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
type: enum<string>RequiredThe Type of this Factor. Currently push
and totp
are supported.
push
totp
Binding.Alg
type: stringThe algorithm used when factor_type
is push
. Algorithm supported: ES256
Binding.PublicKey
type: stringThe Ecdsa public key in PKIX, ASN.1 DER format encoded in Base64.
Required when factor_type
is push
Config.AppId
type: stringThe 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
type: enum<string>The transport technology used to generate the Notification Token. Can be apn
, fcm
or none
.
Required when factor_type
is push
.
apn
fcm
none
Config.NotificationToken
type: stringFor 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.SdkVersion
type: stringThe Verify Push SDK version used to configure the factor
Required when factor_type
is push
Binding.Secret
type: stringThe 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.TimeStep
type: integerDefines 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.Skew
type: integerThe 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.CodeLength
type: integerNumber 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
type: enum<string>The algorithm used to derive the TOTP codes. Can be sha1
, sha256
or sha512
. Defaults to sha1
.
Used when factor_type
is totp
sha1
sha256
sha512
Metadata
type: objectCustom metadata associated with the factor. This is added by the Device/SDK directly to allow for the inclusion of device information. It must be a stringified JSON with only strings values eg. {"os": "Android"}
. Can be up to 1024 characters in length.
Example 1
Example 2
GET
_10https://verify.twilio.com/v2/Services/{ServiceSid}/Entities/{Identity}/Factors/{Sid}
Parameters
Identity
type: stringCustomer 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.
Example 1
GET
_10https://verify.twilio.com/v2/Services/{ServiceSid}/Entities/{Identity}/Factors
Parameters
Identity
type: stringCustomer unique identity for the Entity owner of the Factors. 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.
PageSize
type: integerHow many resources to return in each list page. The default is 50, and the maximum is 1000.
Example 1
POST
_10https://verify.twilio.com/v2/Services/{ServiceSid}/Entities/{Identity}/Factors/{Sid}
Parameters
Identity
type: stringCustomer 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.
AuthPayload
type: stringThe optional payload needed to verify the Factor for the first time. E.g. for a TOTP, the numeric code.
Config.NotificationToken
type: stringFor APN, the device token. For FCM, the registration token. It is used to send the push notifications. Required when factor_type
is push
. If specified, this value must be between 32 and 255 characters long.
Config.TimeStep
type: integerDefines 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
Config.Skew
type: integerThe number of time-steps, past and future, that are valid for validation of TOTP codes. Must be between 0 and 2, inclusive
Config.CodeLength
type: integerNumber of digits for generated TOTP codes. Must be between 3 and 8, inclusive
Config.Alg
type: enum<string>The algorithm used to derive the TOTP codes. Can be sha1
, sha256
or sha512
sha1
sha256
sha512
Config.NotificationPlatform
type: stringThe transport technology used to generate the Notification Token. Can be apn
, fcm
or none
.
Required when factor_type
is push
.
Example 1
Increases time step and code length
DELETE
_10https://verify.twilio.com/v2/Services/{ServiceSid}/Entities/{Identity}/Factors/{Sid}
Parameters
Identity
type: stringCustomer 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.
Example 1