POST /v3/auth/verify-pin

POST

/v3/auth/verify-pin

const url = 'https://api-ha-prod-p8.handbid.dev/v3/auth/verify-pin';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': '*/*'},
  body: '"{\n  \"email\": \"{{email}}\",\n  \"pin\": \"00000\",\n  \"whitelabelId\": {{whitelabelId}}\n}"'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api-ha-prod-p8.handbid.dev/v3/auth/verify-pin \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: */*' \
  --data '"{\n  \"email\": \"{{email}}\",\n  \"pin\": \"00000\",\n  \"whitelabelId\": {{whitelabelId}}\n}"'

Validates the PIN the user received via SMS. On success, mints {accessToken, refreshToken, expiresIn}.

Next step after this runs: the test script captured {{accessToken}} into the environment — now anything in Public or Bidder (auth required) will use it automatically.

The {{email}} in the body is auto-populated by whichever prior step set it (email-check captured it from the request body; register captured it from the request body). If you run this request without first running one of those, {{email}} will be empty and you’ll get a 400 — fill it in manually or run email-check / register first.

Single-use: the PIN is burned on successful validation. Attempting to reuse returns 401 invalid_pin.

Dev shortcut: pin: "00000" validates against any user in docker-dev (params['allowAllZeroPins'] is true). In prod, use the real 5-digit code from the SMS.

Lockout:

5 wrong PINs → isDisabled = 1 (temporary) → 429 rate_limited.
Successful PIN clears fail counter and releases isDisabled.
isLockedOut = 1 (permanent manual ban) → 403 server_error (cannot self-recover).
OGAC whitelabel (4) → 400 registration_blocked (remote auth only).

Authorizations

bearer

Request Body

*/*

string

Example

"{\n  \"email\": \"{{email}}\",\n  \"pin\": \"00000\",\n  \"whitelabelId\": {{whitelabelId}}\n}"

Responses

200

Successful response

application/json