WSS
/
ws-v1-challenge
Messages
Create Challenge
type:object

Message to initiate a new challenge

Challenge Created
type:object

Confirmation of challenge creation

State Change
type:object

Challenge state update

​
Connection

Connect to the WebSocket endpoint for the region of your Tenant.
RegionAPI URL
US (Oregon)wss://api-ws.authsignal.com/ws-v1-challenge
AU (Sydney)wss://au.api-ws.authsignal.com/ws-v1-challenge
EU (Dublin)wss://eu.api-ws.authsignal.com/ws-v1-challenge

​
Authentication

To authenticate with the WebSocket API, include the required values in the Sec-WebSocket-Protocol header:
  1. authsignal-ws - identifies the Authsignal WebSocket sub-protocol.
  2. Exactly one of the following, depending on the type of challenge you are creating:
    • x.authsignal.tenant.<your-tenant-id> - use when the challenge is anonymous (user is not known yet).
    • x.authsignal.token.<token-from-track> - use when the challenge is for a known user; supply the token returned by the track request.

​
Message Flow

The WebSocket communication follows this pattern:
  1. Client connects to the WebSocket endpoint
  2. Client sends CREATE_CHALLENGE message to initiate a challenge
  3. Server responds with CHALLENGE_CREATED confirmation
  4. Server sends STATE_CHANGE messages as the challenge progresses through states

​
Challenge States

Challenges progress through the following states:
  • unclaimed - Challenge created but not yet claimed by a user (This state will not be included in the state change messages)
  • claimed - User has claimed the challenge on their device
  • approved - User has approved the challenge
  • rejected - User has rejected the challenge

​
Example

// Connect to WebSocket
const ws = new WebSocket("wss://api-ws.authsignal.com/ws-v1-challenge", [
  "authsignal-ws",
  "x.authsignal.tenant.5e1eebc0-31c5-42db-b86f-3981f0081ac6",
]);

// Send challenge creation request
ws.send(
  JSON.stringify({
    type: "CREATE_CHALLENGE",
    data: {
      challengeType: "QR_CODE",
      actionCode: "kiosk-login",
    },
  })
);

// Listen for responses
ws.onmessage = (event) => {
  const message = JSON.parse(event.data);

  switch (message.type) {
    case "CHALLENGE_CREATED":
      console.log("Challenge created:", message.data.challengeId);
      break;

    case "STATE_CHANGE":
      console.log("State changed:", message.data.state);
      if (message.data.state === "approved" && message.data.accessToken) {
        console.log("Access token:", message.data.accessToken);
        // Validate the token in your backend
      }
      break;
  }
};