Factor Resource

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.

Factor Properties

For security reasons the binding property is ONLY returned upon creation, and is never returned afterwards.

Resource Properties in REST API format
`sid`	sid<YF> Not PII A 34 character string that uniquely identifies this Factor.
`account_sid`	sid<AC> Not PII The unique SID identifier of the Account.
`service_sid`	sid<VA> Not PII The unique SID identifier of the Service.
`entity_sid`	sid<YE> Not PII The unique SID identifier of the Entity.
`identity`	string PII MTL: 30 DAYS 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.
`binding`	object Not PII Contains 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.
`date_created`	date_time<iso8601> Not PII The date that this Factor was created, given in ISO 8601 format.
`date_updated`	date_time<iso8601> Not PII The date that this Factor was updated, given in ISO 8601 format.
`friendly_name`	string Not PII 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`	enum:factor_statuses Not PII The Status of this Factor. One of `unverified` or `verified`.
`factor_type`	enum:factor_types Not PII The Type of this Factor. Currently `push` and `totp` are supported.
`config`	object Not PII An object that contains configurations specific to a `factor_type`.
`metadata`	object PII MTL: 30 DAYS Custom 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.
`url`	url Not PII The URL of this resource.

Create a new Factor resource

POST

https://verify.twilio.com/v2/Services/{ServiceSid}/Entities/{Identity}/Factors

Unverified Factors will be deleted and unverifiable after 1-24 hours from when they were created. This is done for security and clean-up reasons.

In the request, if the specified 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

Parameters in REST API format
`service_sid` Path	post sid<VA> Not PII The unique SID identifier of the Service.
`identity` Path	post string PII MTL: 30 DAYS 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.
`friendly_name` Required	post string Not PII 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.
`factor_type` Required	post ienum:factor_types Not PII The Type of this Factor. Currently `push` and `totp` are supported.
`binding.alg` Optional	post string Not PII The algorithm used when `factor_type` is `push`. Algorithm supported: `ES256`
`binding.public_key` Optional	post base64 Not PII The Ecdsa public key in PKIX, ASN.1 DER format encoded in Base64. Required when `factor_type` is `push`
`config.app_id` Optional	post string Not PII 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.notification_platform` Optional	post ienum:notification_platforms Not PII The transport technology used to generate the Notification Token. Can be `apn`, `fcm` or `none`. Required when `factor_type` is `push`.
`config.notification_token` Optional	post string Not PII 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.sdk_version` Optional	post string Not PII The Verify Push SDK version used to configure the factor Required when `factor_type` is `push`
`binding.secret` Optional	post string Not PII 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.time_step` Optional	post integer Not PII 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.skew` Optional	post integer Not PII 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.code_length` Optional	post integer Not PII 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` Optional	post ienum:totp_algorithms Not PII The algorithm used to derive the TOTP codes. Can be `sha1`, `sha256` or `sha512`. Defaults to `sha1`. Used when `factor_type` is `totp`
`metadata` Optional	post object PII MTL: 30 DAYS Custom 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

Loading Code Sample...

Example JSON response

Create New Push Factor

Example 2

Loading Code Sample...

Example JSON response

Create New TOTP Factor

Fetch a Factor resource

GET

https://verify.twilio.com/v2/Services/{ServiceSid}/Entities/{Identity}/Factors/{Sid}

Parameters

Parameters in REST API format
`service_sid` Path	get sid<VA> Not PII The unique SID identifier of the Service.
`identity` Path	get string PII MTL: 30 DAYS 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.
`sid` Path	get sid<YF> Not PII A 34 character string that uniquely identifies this Factor.

Parameters in REST API format

service_sid

Path

get sid<VA> Not PII

The unique SID identifier of the Service.

identity

Path

get string PII MTL: 30 DAYS

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.

sid

Path

get sid<YF> Not PII

A 34 character string that uniquely identifies this Factor.

Example 1

Loading Code Sample...

Example JSON response

Fetch a Factor

Read multiple Factor resources

GET

https://verify.twilio.com/v2/Services/{ServiceSid}/Entities/{Identity}/Factors

Parameters

Parameters in REST API format
`service_sid` Path	get sid<VA> Not PII The unique SID identifier of the Service.
`identity` Path	get string PII MTL: 30 DAYS Customer 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.

Parameters in REST API format

service_sid

Path

get sid<VA> Not PII

The unique SID identifier of the Service.

identity

Path

get string PII MTL: 30 DAYS

Customer 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.

Example 1

Loading Code Sample...

Example JSON response

Read multiple Factors

Update a Factor resource

POST

https://verify.twilio.com/v2/Services/{ServiceSid}/Entities/{Identity}/Factors/{Sid}

Parameters

Parameters in REST API format
`service_sid` Path	post sid<VA> Not PII The unique SID identifier of the Service.
`identity` Path	post string PII MTL: 30 DAYS 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.
`sid` Path	post sid<YF> Not PII A 34 character string that uniquely identifies this Factor.
`auth_payload` Optional	post string Not PII The optional payload needed to verify the Factor for the first time. E.g. for a TOTP, the numeric code.
`friendly_name` Optional	post string Not PII The new friendly name of this Factor. It can be up to 64 characters.
`config.notification_token` Optional	post string Not PII For 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.sdk_version` Optional	post string Not PII The Verify Push SDK version used to configure the factor
`config.time_step` Optional	post integer Not PII 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
`config.skew` Optional	post integer Not PII The number of time-steps, past and future, that are valid for validation of TOTP codes. Must be between 0 and 2, inclusive
`config.code_length` Optional	post integer Not PII Number of digits for generated TOTP codes. Must be between 3 and 8, inclusive
`config.alg` Optional	post ienum:totp_algorithms Not PII The algorithm used to derive the TOTP codes. Can be `sha1`, `sha256` or `sha512`
`config.notification_platform` Optional	post string Not PII The transport technology used to generate the Notification Token. Can be `apn`, `fcm` or `none`. Required when `factor_type` is `push`.

Example 1

Loading Code Sample...

Example JSON response

Update a Factor

Loading Code Sample...

Example JSON response

Increases time step and code length

Update a TOTP factor settings

Increases time step and code length

Delete a Factor resource

DELETE

https://verify.twilio.com/v2/Services/{ServiceSid}/Entities/{Identity}/Factors/{Sid}

Parameters

Parameters in REST API format
`service_sid` Path	delete sid<VA> Not PII The unique SID identifier of the Service.
`identity` Path	delete string PII MTL: 30 DAYS 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.
`sid` Path	delete sid<YF> Not PII A 34 character string that uniquely identifies this Factor.

Parameters in REST API format

service_sid

Path

delete sid<VA> Not PII

The unique SID identifier of the Service.

identity

Path

delete string PII MTL: 30 DAYS

sid

Path

delete sid<YF> Not PII

A 34 character string that uniquely identifies this Factor.

Example 1

Loading Code Sample...

Example JSON response

Delete a Factor

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Factor Properties

Create a new Factor resource

Create New Push Factor

Create New TOTP Factor

Fetch a Factor resource

Fetch a Factor

Read multiple Factor resources

Read multiple Factors

Update a Factor resource

Update a Factor

Update a TOTP factor settings

Delete a Factor resource

Delete a Factor

Need some help?

Thank you for your feedback!

Need help? Talk to Support

Thanks for your feedback!