Skip to content
Shortcut: /, ⌘K or Ctrl+K

Passkey pairing

View as Markdown

The passkey ticket object

Attributes

  • versionnumberrequired

    Specifies version for this native passkey ticket.

    Allowed values2
  • ticketstringrequired

    Specifies ticket for this native passkey ticket.

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

  • rpIdstringrequired

    Identifier for the rp.

  • challengeB64Urlstringrequired

    URL for the challenge b64.

  • userVerificationstringrequired

    Specifies user verification for this native passkey ticket.

    Allowed valuespreferredrequireddiscouraged
  • expiresAtstringrequired

    ISO 8601 timestamp when this resource expires.

  • timeoutMsinteger

    Specifies timeout ms for this native passkey ticket.

The passkey ticket object
{
  "version": 2,
  "ticket": "string",
  "session": "string",
  "rpId": "string",
  "challengeB64Url": "string",
  "userVerification": "preferred",
  "expiresAt": "string",
  "timeoutMs": 0
}

Get passkey challenge

GET/messaging/{session}/passkey/challenge/{ticketId}Messaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

Your team must have direct-pairing access for the target Number. Returns the ceremony options for a ticket that has not expired and has not been redeemed.

Path parameters

  • sessionstringrequiredmin length1

    Identifier of the connected Polymorfa session.

  • ticketIdstringrequiredmin length1

    Identifier for the ticket.

Responses

  • 200Live challenge ticket
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 8 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 409No passkey challenge pending for this session
  • 410Passkey ticket expired. Issue a new challenge.
  • 422Assertion is not bound to the ticket challenge
  • 500Internal server error
  • 502Upstream WhatsApp request failed or its response could not be mapped
  • 503Passkey service is temporarily unavailable or the request upload exceeded nine seconds
GET /messaging/{session}/passkey/challenge/{ticketId}cURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/messaging/<session>/passkey/challenge/<ticketId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "data": {
    "version": 2,
    "ticket": "string",
    "session": "string",
    "rpId": "string",
    "challengeB64Url": "string",
    "userVerification": "preferred",
    "expiresAt": "string"
  }
}

Get passkey confirmation

GET/messaging/{session}/passkey/confirmationMessaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

Your team must have direct-pairing access for the target Number. Reports where the ceremony stands: no round-trip, challenge pending, assertion submitted, code available for comparison, confirmation sending, waiting for pairing, completed, or failed.

Path parameters

  • sessionstringrequiredmin length1

    Identifier of the connected Polymorfa session.

Responses

  • 200Round-trip state
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 5 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 409No passkey challenge pending for this session
  • 410Passkey ticket expired. Issue a new challenge.
  • 422Assertion is not bound to the ticket challenge
  • 500Internal server error
  • 502Upstream WhatsApp request failed or its response could not be mapped
  • 503Passkey service is temporarily unavailable or the request upload exceeded nine seconds
GET /messaging/{session}/passkey/confirmationcURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/messaging/<session>/passkey/confirmation" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true,
  "data": {
    "status": "none"
  }
}

Verify extension passkey ticket

POST/passkey/verifyMessaging API
Base URL
https://api.polymorfa.com

Body

  • ticketIdstringrequiredmax length160

    Identifier for the ticket.

  • quicklinkTokenstringmax length160

    Specifies quicklink token for this schema.

Responses

  • 200Canonical v2 ceremony options
    • dataobjectrequired

      Structured data carried by this object.

      Show 15 child fields
  • 400Invalid verification request
  • 404Ticket or attempt unavailable
  • 413Passkey verification body exceeds 1048576 UTF-8 bytes before JSON parsing.
  • 429Rate limited
  • 503Verification unavailable
POST /passkey/verifycURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/passkey/verify" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "ticketId": "string"
}'
Response
{
  "data": {
    "allowCredentials": [
      {
        "id": "string",
        "type": "public-key"
      }
    ],
    "version": 2,
    "ticket": "string",
    "session": "string",
    "teamId": "string",
    "projectId": "string",
    "attemptId": "string",
    "generation": "string",
    "quicklinkId": "string",
    "challengeB64Url": "string",
    "rpId": "whatsapp.com",
    "userVerification": "required",
    "expiresAt": "string",
    "display": {
      "businessName": "string",
      "phoneMasked": "string"
    }
  }
}

Issue passkey challenge

POST/messaging/{session}/passkey/challengeMessaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

Your team must have direct-pairing access for the target Number. Use QuickLink for standard connections. Binds a WhatsApp-originated passkey challenge to one session with a short TTL. The extension runs the ceremony and the assertion comes back to the redeem endpoint.

Path parameters

  • sessionstringrequiredmin length1

    Identifier of the connected Polymorfa session.

Body

  • challengeB64Urlstringmin length1

    Optional expected challenge. If supplied it must match the current runner snapshot; it never supplies ceremony options.

  • userVerificationstringdeprecated

    Ignored. The current runner determines user verification.

    Allowed valuespreferredrequireddiscouraged
  • ttlSecondsinteger

    Requested ticket lifetime, independent of the WebAuthn timeout. Defaults to 300 seconds and is clamped to 255–300 seconds, then capped by the current challenge deadline. No new ticket is issued with less than 255 seconds remaining. The budget includes one minute to enter the ticket, two 10-second verification calls, 30 seconds for explicit consent, 15 seconds for popup startup, a five-second minimum prompt, and a 120-second post-prompt reserve for final verification, one minute to copy the assertion, both direct server RPCs, access checks and transit. A short remaining window is withheld from new callers without retiring an advertised live ticket. Renewal waits for expiry; an explicitly shorter lifetime constraint may retire an unreserved ticket. In-flight forwarding blocks replacement. Current runner authority is revalidated throughout.

  • timeoutMsintegerdeprecatedgreater than0

    Ignored. The current runner determines ceremony timeout.

Responses

  • 200Challenge ticket issued
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 8 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 409No passkey challenge pending for this session
  • 410Passkey ticket expired. Issue a new challenge.
  • 413Passkey body exceeds 1048576 UTF-8 bytes before JSON parsing.
  • 422Assertion is not bound to the ticket challenge
  • 500Internal server error
  • 502Upstream WhatsApp request failed or its response could not be mapped
  • 503Passkey service is temporarily unavailable or the request upload exceeded nine seconds
POST /messaging/{session}/passkey/challengecURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/messaging/<session>/passkey/challenge" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "challengeB64Url": "string",
  "userVerification": "preferred",
  "ttlSeconds": 0,
  "timeoutMs": 0
}'
Response
{
  "success": true,
  "data": {
    "version": 2,
    "ticket": "string",
    "session": "string",
    "rpId": "string",
    "challengeB64Url": "string",
    "userVerification": "preferred",
    "expiresAt": "string"
  }
}

Submit passkey assertion

POST/messaging/{session}/passkey/assertionMessaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

The complete HTTP body is limited to 1048576 UTF-8 bytes before JSON parsing. Credential IDs allow at most 1023 decoded bytes; user handles allow 64. Opaque assertion fields share the body budget without independent small caps. Your team must have direct-pairing access for the target Number. Single-use: verifies the assertion is bound to the ticket challenge, forwards it to the session runner, and consumes the ticket once acknowledged.

Path parameters

  • sessionstringrequiredmin length1

    Identifier of the connected Polymorfa session.

Body

  • ticketIdstringrequiredmin length1

    Identifier for the ticket.

  • assertionobjectrequired

    Specifies assertion for this native submit passkey assertion request.

    Show 3 child fields

Responses

  • 200Assertion accepted
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 3 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 409No passkey challenge pending for this session
  • 410Passkey ticket expired. Issue a new challenge.
  • 413Passkey body exceeds 1048576 UTF-8 bytes before JSON parsing.
  • 422Assertion is not bound to the ticket challenge
  • 500Internal server error
  • 502Upstream WhatsApp request failed or its response could not be mapped
  • 503Passkey service is temporarily unavailable or the request upload exceeded nine seconds
POST /messaging/{session}/passkey/assertioncURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/messaging/<session>/passkey/assertion" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "ticketId": "string",
  "assertion": {
    "id": "string",
    "rawIdB64Url": "string",
    "response": {
      "authenticatorDataB64": "string",
      "clientDataJSONB64": "string",
      "signatureB64": "string"
    }
  }
}'
Response
{
  "success": true,
  "data": {
    "ok": true,
    "ticket": "string",
    "session": "string"
  }
}

Confirm passkey

POST/messaging/{session}/passkey/confirmationMessaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
sessions:manage

Confirm only after comparing the displayed code with the phone. Omit code only when the current runner reports skipHandoffUX. An accepted confirmation still waits for pairing completion.

Path parameters

  • sessionstringrequiredmin length1

    Identifier of the connected Polymorfa session.

Body

  • ticketIdstringrequiredmin length1

    Identifier for the ticket.

  • codestringpattern^[A-Z0-9]{4}-[A-Z0-9]{4}$

    Stable machine-readable code for this result.

Responses

  • 200Confirmation accepted; consult pairing state
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 5 child fields
    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 409No passkey challenge pending for this session
  • 410Passkey ticket expired. Issue a new challenge.
  • 413Passkey body exceeds 1048576 UTF-8 bytes before JSON parsing.
  • 422Assertion is not bound to the ticket challenge
  • 500Internal server error
  • 502Upstream WhatsApp request failed or its response could not be mapped
  • 503Passkey service is temporarily unavailable or the request upload exceeded nine seconds
POST /messaging/{session}/passkey/confirmationcURL
Not available with the Test key. Use a team key or project token.
curl -X POST "https://api.polymorfa.com/messaging/<session>/passkey/confirmation" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "ticketId": "string"
}'
Response
{
  "success": true,
  "data": {
    "status": "none"
  }
}