API Reference

Candidate Access

Token-based API for the candidate interview flow — OTP verification and session management.

Candidate access endpoints use a time-limited token embedded in the interview link (e.g. /interview/join/:token). These endpoints do not require JWT or API key authentication — the token itself is the authentication credential.

Flow Overview

Step	Endpoint	Action
1	GET /candidate-access/:token/info	Load interview details, candidate name, masked email
2	POST /candidate-access/:token/request-otp	Send 6-digit OTP to candidate email
3	POST /candidate-access/:token/verify-otp	Verify OTP, receive session token
4	POST /candidate-access/:token/start	Pass device check, create live interview session

GET /candidate-access/:token/info

Returns public interview info. Called by the join page to display candidate name, position, and masked email before sending the OTP.

bash

curl http://localhost:3009/api/v1/candidate-access/abc123token/info

Response 200

{
  "candidateName": "Jane Smith",
  "position": "Senior Engineer",
  "maskedEmail": "j***@e***.com",
  "expiresAt": "2024-01-20T23:59:59.000Z"
}

Response 404

{
  "statusCode": 404,
  "message": "Interview link not found or has expired"
}

POST /candidate-access/:token/request-otp

Sends a 6-digit one-time password to the candidate's registered email. Valid for 10 minutes. Rate-limited to 5 requests per 10 minutes.

bash

curl -X POST http://localhost:3009/api/v1/candidate-access/abc123token/request-otp

Response 201

{
  "message": "Verification code sent to j***@e***.com"
}

POST /candidate-access/:token/verify-otp

Verifies the 6-digit OTP. On success, returns a session token that is stored in sessionStorage and used for the start endpoint.

bash

curl -X POST http://localhost:3009/api/v1/candidate-access/abc123token/verify-otp \
  -H "Content-Type: application/json" \
  -d '{ "otp": "123456" }'

Response 200

{
  "sessionToken": "session-jwt-token",
  "candidateName": "Jane Smith",
  "position": "Senior Engineer"
}

Response 401

{
  "statusCode": 401,
  "message": "Invalid or expired verification code"
}

The frontend stores the sessionToken in sessionStorage as interview_session_token and uses it in the x-session-token header for the start call.

POST /candidate-access/:token/start

Called after the device pre-check passes. Creates the live interview session and returns a sessionId for the WebSocket connection.

bash

curl -X POST http://localhost:3009/api/v1/candidate-access/abc123token/start \
  -H "x-session-token: session-jwt-token"

Response 201

{
  "sessionId": "session-uuid",
  "tenantId": "tenant-uuid",
  "wsUrl": "ws://localhost:8080"
}

After receiving the response, the frontend navigates to /interview/:sessionId and connects to the WebSocket edge at ws://localhost:8080.

Frontend Session Storage

Key	Value	Set At
interview_session_token	Session JWT	After OTP verify
interview_token	URL access token	After OTP verify
interview_candidate_name	Candidate full name	After OTP verify
interview_position	Job position	After OTP verify
interview_tenant_id	Tenant ID	After start call

Was this page helpful?

Previous← Interviews

NextWorkflow →