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.
A 34 character string that uniquely identifies this Factor.
^YF[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
The unique SID identifier of the Account.
^AC[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
The unique SID identifier of the Service.
^VA[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
The unique SID identifier of the Entity.
^YE[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
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.
The date that this Factor was created, given in ISO 8601 format.
The date that this Factor was updated, given in ISO 8601 format.
A human readable description of this resource, up to 64 characters. For a push factor, this can be the device's name.
The Status of this Factor. One of unverified
or verified
.
unverified
verified
The Type of this Factor. Currently push
and totp
are supported.
push
totp
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.
The URL of this resource.
POST
https://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
The unique SID identifier of the Service.
^VA[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
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.
application/x-www-form-urlencoded
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.
The Type of this Factor. Currently push
and totp
are supported.
push
totp
The algorithm used when factor_type
is push
. Algorithm supported: ES256
The Ecdsa public key in PKIX, ASN.1 DER format encoded in Base64.
Required when factor_type
is push
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
.
The transport technology used to generate the Notification Token. Can be apn
, fcm
or none
.
Required when factor_type
is push
.
apn
fcm
none
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
.
The Verify Push SDK version used to configure the factor
Required when factor_type
is push
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
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
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
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
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
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
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createNewFactor() {11const newFactor = await client.verify.v212.services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.entities("ff483d1ff591898a9942916050d2ca3f")14.newFactors.create({15"binding.alg": "ES256",16"binding.publicKey": "dGVzdF9rZXk=",17"config.appId": "com.example.myapp",18"config.notificationPlatform": "fcm",19"config.notificationToken": "test_token",20"config.sdkVersion": "1.0.0",21factorType: "push",22friendlyName: "John's Phone",23});2425console.log(newFactor.sid);26}2728createNewFactor();
1{2"sid": "YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",5"entity_sid": "YEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",6"identity": "ff483d1ff591898a9942916050d2ca3f",7"binding": {8"alg": "ES256",9"public_key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8GdwtibWe0kpgsFl6xPQBwhtwUEyeJkeozFmi2jiJDzxFSMwVy3kVR1h/dPVYOfgkC0EkfBRJ0J/6xW47FD5vA=="10},11"date_created": "2015-07-30T20:00:00Z",12"date_updated": "2015-07-30T20:00:00Z",13"friendly_name": "John's Phone",14"status": "unverified",15"factor_type": "push",16"config": {17"sdk_version": "1.0",18"app_id": "com.example.myapp",19"notification_platform": "fcm",20"notification_token": "test_token"21},22"metadata": {23"os": "Android"24},25"url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Factors/YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"26}
Example 2
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createNewFactor() {11const newFactor = await client.verify.v212.services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.entities("ff483d1ff591898a9942916050d2ca3f")14.newFactors.create({15"binding.secret": "GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ",16"config.alg": "sha1",17"config.codeLength": 6,18"config.skew": 1,19"config.timeStep": 30,20factorType: "totp",21friendlyName: "John's Phone",22});2324console.log(newFactor.sid);25}2627createNewFactor();
1{2"sid": "YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",5"entity_sid": "YEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",6"identity": "ff483d1ff591898a9942916050d2ca3f",7"binding": {8"secret": "GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ",9"uri": "otpauth://totp/test-issuer:John%E2%80%99s%20Account%20Name?secret=GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ&issuer=test-issuer&algorithm=SHA1&digits=6&period=30"10},11"date_created": "2015-07-30T20:00:00Z",12"date_updated": "2015-07-30T20:00:00Z",13"friendly_name": "John's Phone",14"status": "unverified",15"factor_type": "totp",16"config": {17"alg": "sha1",18"skew": 1,19"code_length": 6,20"time_step": 3021},22"metadata": null,23"url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Factors/YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"24}
GET
https://verify.twilio.com/v2/Services/{ServiceSid}/Entities/{Identity}/Factors/{Sid}
Parameters
The unique SID identifier of the Service.
^VA[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
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.
A 34 character string that uniquely identifies this Factor.
^YF[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
Example 1
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchFactor() {11const factor = await client.verify.v212.services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.entities("Identity")14.factors("YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")15.fetch();1617console.log(factor.sid);18}1920fetchFactor();
1{2"sid": "YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",5"entity_sid": "YEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",6"identity": "Identity",7"date_created": "2015-07-30T20:00:00Z",8"date_updated": "2015-07-30T20:00:00Z",9"friendly_name": "friendly_name",10"status": "unverified",11"factor_type": "push",12"config": {13"sdk_version": "1.0",14"app_id": "com.example.myapp",15"notification_platform": "fcm",16"notification_token": "test_token"17},18"metadata": {19"os": "Android"20},21"url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Factors/YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"22}
GET
https://verify.twilio.com/v2/Services/{ServiceSid}/Entities/{Identity}/Factors
Parameters
The unique SID identifier of the Service.
^VA[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
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.
How many resources to return in each list page. The default is 50, and the maximum is 1000.
1
Maximum: 1000
The page token. This is provided by the API.
Example 1
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function listFactor() {11const factors = await client.verify.v212.services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.entities("ff483d1ff591898a9942916050d2ca3f")14.factors.list({ limit: 20 });1516factors.forEach((f) => console.log(f.sid));17}1819listFactor();
1{2"factors": [],3"meta": {4"page": 0,5"page_size": 50,6"first_page_url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Factors?PageSize=50&Page=0",7"previous_page_url": null,8"url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Factors?PageSize=50&Page=0",9"next_page_url": null,10"key": "factors"11}12}
POST
https://verify.twilio.com/v2/Services/{ServiceSid}/Entities/{Identity}/Factors/{Sid}
Parameters
The unique SID identifier of the Service.
^VA[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
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.
A 34 character string that uniquely identifies this Factor.
^YF[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
application/x-www-form-urlencoded
The optional payload needed to verify the Factor for the first time. E.g. for a TOTP, the numeric code.
The new friendly name of this Factor. It can be up to 64 characters.
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.
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 number of time-steps, past and future, that are valid for validation of TOTP codes. Must be between 0 and 2, inclusive
Number of digits for generated TOTP codes. Must be between 3 and 8, inclusive
The algorithm used to derive the TOTP codes. Can be sha1
, sha256
or sha512
sha1
sha256
sha512
The transport technology used to generate the Notification Token. Can be apn
, fcm
or none
.
Required when factor_type
is push
.
Example 1
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function updateFactor() {11const factor = await client.verify.v212.services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.entities("ff483d1ff591898a9942916050d2ca3f")14.factors("YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")15.update({ authPayload: "724590" });1617console.log(factor.sid);18}1920updateFactor();
1{2"sid": "YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",5"entity_sid": "YEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",6"identity": "ff483d1ff591898a9942916050d2ca3f",7"date_created": "2015-07-30T20:00:00Z",8"date_updated": "2015-07-30T20:00:00Z",9"friendly_name": "friendly_name",10"status": "verified",11"factor_type": "push",12"config": {13"sdk_version": "1.0",14"app_id": "com.example.myapp",15"notification_platform": "fcm",16"notification_token": "test_token"17},18"metadata": {19"os": "Android"20},21"url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Factors/YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"22}
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function updateFactor() {11const factor = await client.verify.v212.services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.entities("ff483d1ff591898a9942916050d2ca3f")14.factors("YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")15.update({16"config.codeLength": 8,17"config.timeStep": 45,18});1920console.log(factor.config);21}2223updateFactor();
1{2"sid": "YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",5"entity_sid": "YEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",6"identity": "ff483d1ff591898a9942916050d2ca3f",7"date_created": "2015-07-30T20:00:00Z",8"date_updated": "2015-07-30T20:00:00Z",9"friendly_name": "friendly_name",10"status": "verified",11"factor_type": "push",12"config": {13"sdk_version": "1.0",14"app_id": "com.example.myapp",15"notification_platform": "fcm",16"notification_token": "test_token"17},18"metadata": {19"os": "Android"20},21"url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Factors/YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"22}
DELETE
https://verify.twilio.com/v2/Services/{ServiceSid}/Entities/{Identity}/Factors/{Sid}
Parameters
The unique SID identifier of the Service.
^VA[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
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.
A 34 character string that uniquely identifies this Factor.
^YF[0-9a-fA-F]{32}$
Min length: 34
Max length: 34
Example 1
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function deleteFactor() {11await client.verify.v212.services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.entities("ff483d1ff591898a9942916050d2ca3f")14.factors("YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")15.remove();16}1718deleteFactor();