WebSocket

Documentation Index

Fetch the complete documentation index at: https://docs.authsignal.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Connection

​

Authentication

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

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

• 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;
  }
};

{
  "type": "CREATE_CHALLENGE",
  "data": {
    "challengeType": "QR_CODE",
    "actionCode": "payment-qr-code",
    "custom": {
      "amount": 2499.99,
      "currency": "USD"
    }
  }
}

{
  "type": "CHALLENGE_CREATED",
  "data": {
    "challengeId": "gxl9j7",
    "challengeType": "QR_CODE",
    "expiresAt": "2025-07-09T03:53:16.000Z",
    "state": "unclaimed"
  }
}

{
  "type": "STATE_CHANGE",
  "data": {
    "challengeId": "gxl9j7",
    "state": "claimed"
  }
}