Skip to contentSkip to navigationSkip to topbar
Twilio Docs
Page tools
On this page
Looking for more inspiration?Visit the

Challenge Resource

The Passkeys Challenge resource represents a single verification attempt of a Service, an Entity or a Factor.

Challenge Properties

challenge-properties page anchor
Property nameTypeRequiredPIIDescriptionChild properties
sidSID<YC>

Optional

Not PII

A 34 character string that uniquely identifies this Challenge.

Pattern: ^YC[0-9a-fA-F]{32}$Min length: 34Max length: 34
accountSidSID<AC>

Optional

Not PII

The unique SID identifier of the Account.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
serviceSidSID<VA>

Optional

Not PII

The unique SID identifier of the Service.

Pattern: ^VA[0-9a-fA-F]{32}$Min length: 34Max length: 34
entitySidSID<YE>

Optional

Not PII

The unique SID identifier of the Entity.

Pattern: ^YE[0-9a-fA-F]{32}$Min length: 34Max length: 34
identitystring

Optional

PII MTL: 30 days

Customer unique identity for the Entity owner of the Challenge.

factorSidSID<YF>

Optional

Not PII

The unique SID identifier of the Factor.

Pattern: ^YF[0-9a-fA-F]{32}$Min length: 34Max length: 34
dateCreatedstring<date-time>

Optional

Not PII

The date that this Challenge was created, given in ISO 8601(link takes you to an external page) format.

dateUpdatedstring<date-time>

Optional

Not PII

The date that this Challenge was updated, given in ISO 8601(link takes you to an external page) format.

dateRespondedstring<date-time>

Optional

Not PII

The date that this Challenge was responded, given in ISO 8601(link takes you to an external page) format.

expirationDatestring<date-time>

Optional

Not PII

The date-time when this Challenge expires, given in ISO 8601(link takes you to an external page) format.

statusenum<string>

Optional

Not PII

The Status of this Challenge. One of pending, expired, approved or denied.

Possible values:
pendingexpiredapproveddenied
respondedReasonenum<string>

Optional

Not PII

Reason for the Challenge to be in certain status. One of none, not_needed or not_requested.

Possible values:
nonenot_needednot_requested
details

Optional

PII MTL: 30 days

Details provided to give context about the Challenge.

hiddenDetails

Optional

PII MTL: 30 days

Details provided to give context about the Challenge.

metadata

Optional

PII MTL: 30 days

Custom metadata associated with the challenge.

factorTypeenum<string>

Optional

Not PII

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

Possible values:
pushtotppasskeys
urlstring<uri>

Optional

Not PII

The URL of this resource.

linksobject<uri-map>

Optional

Not PII

Contains a dictionary of URL links to nested resources of this Challenge.

optionsobject

Optional

Not PII

An object that contains challenge options. Currently only used for passkeys.

Create a Passkeys Challenge resource

create-a-passkeys-challenge-resource page anchor

POST https://verify.twilio.com/v2/Services/{ServiceSid}/Passkeys/Challenges

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
serviceSidSID<VA>
required
Not PII

The unique SID identifier of the Service.

Pattern: ^VA[0-9a-fA-F]{32}$Min length: 34Max length: 34

Request body parameters

request-body-parameters page anchor
Encoding type:application/json
SchemaExample
Property nameTypeRequiredPIIDescriptionChild properties
identitystring

Optional

Not PII
factorSidstring

Optional

Not PII
Create a Passkeys ChallengeLink to code sample: Create a Passkeys Challenge
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function createChallengePasskeys() {

11
  const newChallenge = await client.verify.v2

12
    .services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .newChallenge()

14
    .create({

15
      identity: "identity",

16
    });

17


18
  console.log(newChallenge.sid);

19
}

20


21
createChallengePasskeys();

Response

Note about this response
1
{

2
  "sid": "YCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

4
  "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
  "entity_sid": "",

6
  "identity": "identity",

7
  "factor_sid": "",

8
  "factor_type": "passkeys",

9
  "status": "pending",

10
  "date_created": "2025-07-30T20:00:00Z",

11
  "date_updated": "2025-07-30T20:00:00Z",

12
  "date_responded": null,

13
  "details": null,

14
  "expiration_date": null,

15
  "hidden_details": null,

16
  "links": null,

17
  "metadata": null,

18
  "responded_reason": "none",

19
  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Passkeys/Challenges",

20
  "options": {

21
    "publicKey": {

22
      "rp": {

23
        "id": "example.com",

24
        "name": "Example"

25
      },

26
      "user": {

27
        "id": "WUU0ZmQzYWFmNGU0NTMyNGQwZjNlMTM0NjA3YjIxOTEyYg",

28
        "name": "friendly_name",

29
        "displayName": "friendly_name"

30
      },

31
      "challenge": "WUYwNDhkMWE3ZWMzYTJhNjk3MDA1OWMyNzY2YmJjN2UwZg",

32
      "pubKeyCredParams": {

33
        "type": "public-key",

34
        "alg": -7

35
      },

36
      "timeout": 600000,

37
      "excludeCredentials": [],

38
      "authenticatorSelection": {

39
        "authenticatorAttachment": "platform",

40
        "requireResidentKey": false,

41
        "residentKey": "preferred",

42
        "userVerification": "preferred"

43
      },

44
      "attestation": "none"

45
    }

46
  }

47
}

Approve a Passkeys Challenge resource

approve-a-passkeys-challenge-resource page anchor

POST https://verify.twilio.com/v2/Services/{ServiceSid}/Passkeys/ApproveChallenge

Path parameters

path-parameters-1 page anchor
Property nameTypeRequiredPIIDescription
serviceSidSID<VA>
required
Not PII

The unique SID identifier of the Service.

Pattern: ^VA[0-9a-fA-F]{32}$Min length: 34Max length: 34

Request body parameters

request-body-parameters-1 page anchor
Encoding type:application/json
SchemaExample
Property nameTypeRequiredPIIDescriptionChild properties
idstring
required
Not PII

A base64url(link takes you to an external page) encoded representation of rawId.

rawIdstring
required
Not PII

The globally unique identifier for this PublicKeyCredential.

authenticatorAttachmentenum<string>
required
Not PII

A string that indicates the mechanism by which the WebAuthn implementation is attached to the authenticator at the time the associated navigator.credentials.create() or navigator.credentials.get() call completes.

Possible values:
platformcross-platform
typeenum<string>

Optional

Not PII

The valid credential types supported by the API. The values of this enumeration are used for versioning the AuthenticatorAssertion and AuthenticatorAttestation structures according to the type of the authenticator.

Default: public-keyPossible values:
public-key
responseobject
required
Not PII

The result of a WebAuthn authentication via a navigator.credentials.get() request, as specified in AuthenticatorAttestationResponse(link takes you to an external page).

Approve a Passkeys Challenge resourceLink to code sample: Approve a Passkeys Challenge resource
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function updateChallengePasskeys() {

11
  const approveChallenge = await client.verify.v2

12
    .services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .approveChallenge.update({

14
      id: "id",

15
      rawId: "rawId",

16
      authenticatorAttachment: "platform",

17
      response: {

18
        authenticatorData: "authenticatorData",

19
        clientDataJSON: "clientDataJSON",

20
        signature: "signature",

21
        userHandle: "userHandle",

22
      },

23
    });

24


25
  console.log(approveChallenge.sid);

26
}

27


28
updateChallengePasskeys();

Response

Note about this response
1
{

2
  "sid": "YCaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

4
  "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
  "entity_sid": "",

6
  "identity": "",

7
  "factor_sid": "",

8
  "factor_type": "passkeys",

9
  "status": "approved",

10
  "date_created": "2025-07-30T20:00:00Z",

11
  "date_updated": "2025-07-30T20:00:00Z",

12
  "date_responded": null,

13
  "details": null,

14
  "expiration_date": null,

15
  "hidden_details": null,

16
  "links": null,

17
  "metadata": null,

18
  "responded_reason": "none",

19
  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Passkeys/ApproveChallenge",

20
  "options": {

21
    "publicKey": {

22
      "rp": {

23
        "id": "example.com",

24
        "name": "Example"

25
      },

26
      "user": {

27
        "id": "WUU0ZmQzYWFmNGU0NTMyNGQwZjNlMTM0NjA3YjIxOTEyYg",

28
        "name": "friendly_name",

29
        "displayName": "friendly_name"

30
      },

31
      "challenge": "WUYwNDhkMWE3ZWMzYTJhNjk3MDA1OWMyNzY2YmJjN2UwZg",

32
      "pubKeyCredParams": {

33
        "type": "public-key",

34
        "alg": -7

35
      },

36
      "timeout": 600000,

37
      "excludeCredentials": [],

38
      "authenticatorSelection": {

39
        "authenticatorAttachment": "platform",

40
        "requireResidentKey": false,

41
        "residentKey": "preferred",

42
        "userVerification": "preferred"

43
      },

44
      "attestation": "none"

45
    }

46
  }

47
}