WebSocket

​

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