Create a new Factor for the Entity

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

TODO: Resource-level docs

Path parameters

ServiceSid string Required

The unique SID identifier of the Service.
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.

Body

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

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

Used when factor_type is totp

Values are sha1, sha256, or sha512.
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.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.NotificationPlatform string

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

Required when factor_type is push.

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
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.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
FactorType string Required

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

Values are push or totp.
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.
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

Created
Hide response attributes Show response attributes object
- account_sid string | null
  
  Account Sid.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.
- binding
  
  Binding of the factor
- config
  
  Configurations for a factor_type.
- date_created string(date-time) | null
  
  The date this Factor was created
- date_updated string(date-time) | null
  
  The date this Factor was updated
- entity_sid string | null
  
  Entity Sid.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^YE[0-9a-fA-F]{32}$.
- factor_type string | null
  
  The Type of this Factor
  
  Values are push or totp.
- friendly_name string | null
  
  A human readable description of this resource.
- identity string | null
  
  Unique external identifier of the Entity
- metadata
  
  Metadata of the factor.
- service_sid string | null
  
  Service Sid.
  
  Minimum length is 34, maximum length is 34. Format should match the following pattern: ^VA[0-9a-fA-F]{32}$.
- sid string | null
  
  A 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}$.
- status string | null
  
  The Status of this Factor
  
  Values are unverified or verified.
- url string(uri) | null
  
  The URL of this resource.

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

curl \
 -X POST https://verify.twilio.com/v2/Services/{ServiceSid}/Entities/{Identity}/Factors \
 --user "username:password" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'Binding.Alg=string&Binding.PublicKey=string&Binding.Secret=string&Config.Alg=sha1&Config.AppId=string&Config.CodeLength=42&Config.NotificationPlatform=apn&Config.NotificationToken=string&Config.SdkVersion=string&Config.Skew=42&Config.TimeStep=42&FactorType=push&FriendlyName=string'

Request example

{
  "Binding.Alg": "string",
  "Binding.PublicKey": "string",
  "Binding.Secret": "string",
  "Config.Alg": "sha1",
  "Config.AppId": "string",
  "Config.CodeLength": 42,
  "Config.NotificationPlatform": "apn",
  "Config.NotificationToken": "string",
  "Config.SdkVersion": "string",
  "Config.Skew": 42,
  "Config.TimeStep": 42,
  "FactorType": "push",
  "FriendlyName": "string"
}

Request examples

{
  "Binding.Alg": "string",
  "Binding.PublicKey": "string",
  "Binding.Secret": "string",
  "Config.Alg": "sha1",
  "Config.AppId": "string",
  "Config.CodeLength": 42,
  "Config.NotificationPlatform": "apn",
  "Config.NotificationToken": "string",
  "Config.SdkVersion": "string",
  "Config.Skew": 42,
  "Config.TimeStep": 42,
  "FactorType": "push",
  "FriendlyName": "string"
}

Response examples (201)

{
  "account_sid": "string",
  "date_created": "2023-05-04T09:42:00+00:00",
  "date_updated": "2023-05-04T09:42:00+00:00",
  "entity_sid": "string",
  "factor_type": "push",
  "friendly_name": "string",
  "identity": "string",
  "service_sid": "string",
  "sid": "string",
  "status": "unverified",
  "url": "https://example.com"
}

Response examples (201)

{
  "account_sid": "string",
  "date_created": "2024-05-04T09:42:00+00:00",
  "date_updated": "2024-05-04T09:42:00+00:00",
  "entity_sid": "string",
  "factor_type": "push",
  "friendly_name": "string",
  "identity": "string",
  "service_sid": "string",
  "sid": "string",
  "status": "unverified",
  "url": "https://example.com"
}