メニュー

Expand
ページを評価:

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.

Verify TOTP is currently in the Pilot maturity stage, which means that you need to contact sales to request that your Twilio account gets access to it. The Factor properties related to Verify TOTP will not work without this access.

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
文字列 PII MTL: 30 DAYS

The unique external identifier for the Entity of the Service. This identifier should be immutable, not PII, and generated by your external system, such as your user's UUID, GUID, or SID. This value must be between 8 and 64 characters long.

binding
オブジェクト 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
文字列 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. For totp to work, you need to contact Twilio sales first to have the Verify TOTP feature enabled for your Twilio account.

config
オブジェクト Not PII

An object that contains the binding of specific to a factor_type upon creation. Contains the shared secret between Twilio and the client.

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 in REST API format
service_sid
Path
post sid<VA> Not PII

The unique SID identifier of the Service.

identity
Path
post 文字列 PII MTL: 30 DAYS

Customer unique identity for the Entity owner of the Factor. This value must be between 8 and 64 characters long.

friendly_name
必須
post 文字列 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
必須
post ienum:factor_types Not PII

The Type of this Factor. Currently push and totp are supported. For totp to work, you need to contact Twilio sales first to have the Verify TOTP feature enabled for your Twilio account.

binding.alg
オプション
post 文字列 Not PII

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

binding.public_key
オプション
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
オプション
post 文字列 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
オプション
post ienum:notification_platforms Not PII

The transport technology used to generate the Notification Token. Can be apn or fcm.

Required when factor_type is push.

config.notification_token
オプション
post 文字列 Not PII

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

Required when factor_type is push.

config.sdk_version
オプション
post 文字列 Not PII

The Verify Push SDK version used to configure the factor

Required when factor_type is push

binding.secret
オプション
post 文字列 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
オプション
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
オプション
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
オプション
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
オプション
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

例 1

        
        
        

        例 2

              
              
              

              Fetch a Factor resource

              GET

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

              パラメーター

              Parameters in REST API format
              service_sid
              Path
              GET sid<VA> Not PII

              The unique SID identifier of the Service.

              identity
              Path
              GET 文字列 PII MTL: 30 DAYS

              Customer unique identity for the Entity owner of the Factor. This value must be between 8 and 64 characters long.

              sid
              Path
              GET sid<YF> Not PII

              A 34 character string that uniquely identifies this Factor.

              例 1

                    
                    
                    

                    Read multiple Factor resources

                    GET

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

                    パラメーター

                    Parameters in REST API format
                    service_sid
                    Path
                    GET sid<VA> Not PII

                    The unique SID identifier of the Service.

                    identity
                    Path
                    GET 文字列 PII MTL: 30 DAYS

                    Customer unique identity for the Entity owner of the Factor. This value must be between 8 and 64 characters long.

                    例 1

                          
                          
                          

                          Update a Factor resource

                          POST

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

                          パラメーター

                          Parameters in REST API format
                          service_sid
                          Path
                          post sid<VA> Not PII

                          The unique SID identifier of the Service.

                          identity
                          Path
                          post 文字列 PII MTL: 30 DAYS

                          Customer unique identity for the Entity owner of the Factor. This value must be between 8 and 64 characters long.

                          sid
                          Path
                          post sid<YF> Not PII

                          A 34 character string that uniquely identifies this Factor.

                          auth_payload
                          オプション
                          post 文字列 Not PII

                          The optional payload needed to verify the Factor for the first time. E.g. for a TOTP, the numeric code.

                          friendly_name
                          オプション
                          post 文字列 Not PII

                          The new friendly name of this Factor. It can be up to 64 characters.

                          config.notification_token
                          オプション
                          post 文字列 Not PII

                          For APN, the device token. For FCM the registration token. It 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
                          オプション
                          post 文字列 Not PII

                          The Verify Push SDK version used to configure the factor

                          config.time_step
                          オプション
                          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
                          オプション
                          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
                          オプション
                          post integer Not PII

                          Number of digits for generated TOTP codes. Must be between 3 and 8, inclusive

                          config.alg
                          オプション
                          post ienum:totp_algorithms Not PII

                          The algorithm used to derive the TOTP codes. Can be sha1, sha256 or sha512

                          例 1

                                
                                
                                

                                Delete a Factor resource

                                削除

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

                                パラメーター

                                Parameters in REST API format
                                service_sid
                                Path
                                削除する sid<VA> Not PII

                                The unique SID identifier of the Service.

                                identity
                                Path
                                削除する 文字列 PII MTL: 30 DAYS

                                Customer unique identity for the Entity owner of the Factor. This value must be between 8 and 64 characters long.

                                sid
                                Path
                                削除する sid<YF> Not PII

                                A 34 character string that uniquely identifies this Factor.

                                例 1

                                      
                                      
                                      
                                      ページを評価:

                                      ヘルプが必要ですか?

                                      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 Community Forums or browsing the Twilio tag on Stack Overflow.

                                            
                                            
                                            

                                            フィードバックくださりありがとうございます!

                                            We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

                                            Sending your feedback...
                                            🎉 Thank you for your feedback!
                                            Something went wrong. Please try again.

                                            Thanks for your feedback!

                                            Refer us and get $10 in 3 simple steps!

                                            ステップ1

                                            Get link

                                            Get a free personal referral link here

                                            ステップ2:

                                            Give $10

                                            Your user signs up and upgrade using link

                                            ステップ3

                                            Get $10

                                            1,250 free SMSes
                                            OR 1,000 free voice mins
                                            OR 12,000 chats
                                            OR more