WebSocket

​

Connection

Connect to the WebSocket endpoint for the region of your Tenant.

​

Authentication

To authenticate with the WebSocket API, you need to provide the following headers in the Sec-WebSocket-Protocol header: authsignal-ws and x.authsignal.tenant.<your-tenant-id>.

​

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