Create a new Factor for the Entity

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

Account sid auth token

Path parameters

ServiceSid string Required

The unique SID identifier of the Service.

Minimum length is 34, maximum length is 34. Format should match the following pattern: ^VA[0-9a-fA-F]{32}$.
Identity string 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.

application/x-www-form-urlencoded

Body

FriendlyName string 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 string Required

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

Values are push or totp.
Binding.Alg string

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

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

Required when factor_type is push
Config.AppId string

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 string

Values are apn, fcm, or none.
Config.NotificationToken string

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.SdkVersion string

The Verify Push SDK version used to configure the factor

Required when factor_type is push
Binding.Secret string

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.TimeStep integer

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 integer

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.CodeLength integer

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 string

Values are sha1, sha256, or sha512.
Metadata

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.

Responses

201 application/json

Created
Hide headers attributes Show headers attributes
- Access-Control-Allow-Origin string
  
  Specify the origin(s) allowed to access the resource
- Access-Control-Allow-Methods string
  
  Specify the HTTP methods allowed when accessing the resource
- Access-Control-Allow-Headers string
  
  Specify the headers allowed when accessing the resource
- Access-Control-Allow-Credentials boolean
  
  Indicates whether the browser should include credentials
- Access-Control-Expose-Headers string
  
  Headers exposed to the client
Hide response attributes Show response attributes object
- sid string | null
  
  A 34 character string that uniquely identifies this Factor.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^YF[0-9a-fA-F]{32}$.
- account_sid string | null
  
  The unique SID identifier of the Account.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.
- service_sid string | null
  
  The unique SID identifier of the Service.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^VA[0-9a-fA-F]{32}$.
- entity_sid string | null
  
  The unique SID identifier of the Entity.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^YE[0-9a-fA-F]{32}$.
- identity string | null
  
  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
  
  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 string(date-time) | null
  
  The date that this Factor was created, given in ISO 8601 format.
- date_updated string(date-time) | null
  
  The date that this Factor was updated, given in ISO 8601 format.
- friendly_name string | null
  
  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 string
  
  The Status of this Factor. One of unverified or verified.
  
  Values are unverified or verified.
- factor_type string
  
  The Type of this Factor. Currently push and totp are supported.
  
  Values are push or totp.
- config
  
  An object that contains configurations specific to a factor_type.
- metadata
  
  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 string(uri) | null
  
  The URL of this resource.

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

curl \
 --request POST 'https://verify.twilio.com/v2/Services/{ServiceSid}/Entities/{Identity}/Factors' \
 --user "username:password" \
 --header "Content-Type: application/x-www-form-urlencoded" \
 --data 'Metadata=%7B%22os%22%3A+%22Android%22%7D&FactorType=push&Binding.Alg=ES256&Config.AppId=com.example.myapp&FriendlyName=FriendlyName&Binding.PublicKey=dGVzdF9rZXk%3D&Config.SdkVersion=1.0&Config.NotificationToken=test_token&Config.NotificationPlatform=fcm'

Request examples

{"Metadata" => "{\"os\": \"Android\"}", "FactorType" => "push", "Binding.Alg" => "ES256", "Config.AppId" => "com.example.myapp", "FriendlyName" => "FriendlyName", "Binding.PublicKey" => "dGVzdF9rZXk=", "Config.SdkVersion" => "1.0", "Config.NotificationToken" => "test_token", "Config.NotificationPlatform" => "fcm"}

{"Config.Alg" => "sha1", "FactorType" => "totp", "Config.Skew" => 1, "FriendlyName" => "FriendlyName", "Binding.Secret" => "GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ", "Config.TimeStep" => 30, "Config.CodeLength" => 6}

Response examples (201)

{
  "sid": "YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Factors/YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "config": {
    "app_id": "com.example.myapp",
    "sdk_version": "1.0",
    "notification_token": "test_token",
    "notification_platform": "fcm"
  },
  "status": "unverified",
  "binding": {
    "alg": "ES256",
    "public_key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE8GdwtibWe0kpgsFl6xPQBwhtwUEyeJkeozFmi2jiJDzxFSMwVy3kVR1h/dPVYOfgkC0EkfBRJ0J/6xW47FD5vA=="
  },
  "identity": "ff483d1ff591898a9942916050d2ca3f",
  "metadata": {
    "os": "Android"
  },
  "entity_sid": "YEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "factor_type": "push",
  "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "date_created": "2015-07-30T20:00:00Z",
  "date_updated": "2015-07-30T20:00:00Z",
  "friendly_name": "friendly_name"
}

{
  "sid": "YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Factors/YFaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "config": {
    "alg": "sha1",
    "skew": 1,
    "time_step": 30,
    "code_length": 6
  },
  "status": "unverified",
  "binding": {
    "uri": "otpauth://totp/test-issuer:John%E2%80%99s%20Account%20Name?secret=GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ&issuer=test-issuer&algorithm=SHA1&digits=6&period=30",
    "secret": "GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ"
  },
  "identity": "ff483d1ff591898a9942916050d2ca3f",
  "metadata": null,
  "entity_sid": "YEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "factor_type": "totp",
  "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "date_created": "2015-07-30T20:00:00Z",
  "date_updated": "2015-07-30T20:00:00Z",
  "friendly_name": "friendly_name"
}