Skip to content
Handbid Developers

POST /v3/auction/{auctionId}/access — exchange invitation code (private events)

POST
/v3/auction/{auctionId}/access

Exchange the organizer’s invitation code for a 72h access grant (accessToken), then present it in the X-Auction-Access header on the gated reads (HAN-2505). Anonymous or authenticated alike.

400 invalid_invitation_code covers a wrong code, wrong-length code, or blank stored code — deliberately indistinguishable so it is not an oracle. 400 not_a_private_event, 503 when the grant secret is unconfigured. Two limiter budgets: auctionAccessExchange (backstop) and auctionAccessExchangeFail (after a failed compare).

Success body: {accessToken, expiresAt} (the by-key route additionally returns auctionId).

Auth: none.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
Media type application/json
object
invitationCode
required
string
Example 
AB-12!

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Grant issued.

Media type application/json
object
accessToken
string
expiresAt
integer
Example generated
{
  "accessToken": "example",
  "expiresAt": 1
}

400

Section titled “400 ”

Validation error.

Media type application/json

Unified error envelope. retryAfter is present only on transient (429 / 503) responses.

object
error
required

Stable machine-readable error code (e.g. unauthorized, forbidden, not_found, validation_error, unavailable).

string
message
required

Human-readable explanation.

string
retryAfter

Seconds to wait before retrying. Present on 429 and 503.

integer
Example generated
{
  "error": "example",
  "message": "example",
  "retryAfter": 1
}

429

Section titled “429 ”

Rate limited; Retry-After seconds.

Media type application/json

Unified error envelope. retryAfter is present only on transient (429 / 503) responses.

object
error
required

Stable machine-readable error code (e.g. unauthorized, forbidden, not_found, validation_error, unavailable).

string
message
required

Human-readable explanation.

string
retryAfter

Seconds to wait before retrying. Present on 429 and 503.

integer
Example generated
{
  "error": "example",
  "message": "example",
  "retryAfter": 1
}

503

Section titled “503 ”

Access-grant secret unconfigured (access routes only).

Media type application/json

Unified error envelope. retryAfter is present only on transient (429 / 503) responses.

object
error
required

Stable machine-readable error code (e.g. unauthorized, forbidden, not_found, validation_error, unavailable).

string
message
required

Human-readable explanation.

string
retryAfter

Seconds to wait before retrying. Present on 429 and 503.

integer
Example generated
{
  "error": "example",
  "message": "example",
  "retryAfter": 1
}