Skip to main content
POST
/
instances
/
{instanceId}
/
token
/
{token}
/
passkey-prologue
Complete the Challenge
curl --request POST \
  --url https://api.z-api.io/instances/{instanceId}/token/{token}/passkey-prologue \
  --header 'Client-Token: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": "<string>",
  "rawId": "<string>",
  "type": "<string>",
  "response": {
    "authenticatorData": "<string>",
    "clientDataJSON": "<string>",
    "signature": "<string>",
    "userHandle": "<string>"
  }
}
'

​
Overview

On some devices, WhatsApp has started requiring an additional verification step when attempting to connect to WhatsApp Web, called Passkey. Because of this, devices that try to read the QR Code via the API may receive a Challenge in return.
This method is part of the instance connection flow via Passkey (WebAuthn), being the final step of this process:
  1. The QR Code endpoint is called and returns a challenge.
  2. This challenge is resolved on the device / authenticator (a procedure performed outside of Z-API, and that does not depend on our API).
  3. The result of this resolution (the WebAuthn assertion) is sent to this endpoint, so the instance can complete the connection.
The challenge resolution happens directly between the user’s device and the authenticator (Passkey), outside the Z-API ecosystem. This endpoint only receives the already processed result.With this new WhatsApp authentication in mind, Z-API created an extension called Z-API Connector, specifically to make this Passkey validation easier.

​
Attributes

​
Required

​
instanceId
string
required
Your instance ID. Available in the Z-API panel under Instances.
​
token
string
required
Your Z-API instance token.

​
Required

​
id
string
required
Identifier of the credential generated by the authenticator
​
rawId
string
required
Raw identifier of the credential
​
type
string
required
Credential type. Always “public-key”
​
response
object
required
WebAuthn signature data returned by the authenticator

​
Optional

​
clientExtensionResults
object
Client extensions returned by the authenticator

​
Request Body

{
  "id": "...",
  "rawId": "...",
  "type": "public-key",
  "response": {
    "authenticatorData": "...",
    "clientDataJSON": "...",
    "signature": "...",
    "userHandle": null
  },
  "clientExtensionResults": { "uvm": [] }
}

​
Response

​
200

Returns the result of the assertion processing by the instance. There are three possible variations: Success: 
{ "success": true }
Failure — missing required fields: 
{ "success": false, "reason": "assertion (rawId + response) is required" }
Failure — invalid field type: 
{ "success": false, "reason": "assertion fields must be strings" }
Responses with success: false indicate that the assertion payload is malformed — the request body must be corrected and resent. These are not Z-API infrastructure errors.

​
400

Returned in the following cases:
  • Instance not found for the instanceId + token pair:
{ "error": "Instance not found", "value": null }

​
405

In this case, make sure you are sending the correct method specification, i.e., check whether you sent a POST or GET request as specified at the beginning of this topic.

​
415

If you receive a 415 error, make sure to add the “Content-Type” of the object you are sending to the request headers, most commonly “application/json”.