Skip to content
Handbid Developers

POST /v3/auctions/by-key/{key}/access — exchange invitation code by key

POST
/v3/auctions/by-key/{key}/access
 
curl --request POST \
  --url https://api-ha-prod-p8.handbid.dev/v3/auctions/by-key/spring-gala/access \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "invitationCode": "AB-12!" }'

The same exchange as the id route, reached by auction key — the identifier the web holds when the 403 private_event_pin_required denial (which carries no id) refuses it (HAN-2904). Scoped by whitelabelKey/whitelabelId (key wins). Failures are the id route’s verbatim; an unknown key → 404 not_found (treating it as a wrong code would make it a key oracle). Both limiter budgets are the id route’s by name.

Success body adds auctionId — the grant is per-id and every other gated read is id-keyed, so a by-key caller needs it to attach X-Auction-Access. The id route’s body stays {accessToken, expiresAt}.

Auth: none.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
key
required
string
Example 
spring-gala

Query Parameters

Section titled “Query Parameters ”
whitelabelKey
string

Whitelabel slug; wins over whitelabelId when both are sent.

whitelabelId
integer

Numeric whitelabel scope (native callers).

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 (with auctionId).

Media type application/json
object
accessToken
string
expiresAt
integer
auctionId
integer
Example generated
{
  "accessToken": "example",
  "expiresAt": 1,
  "auctionId": 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
}

404

Section titled “404 ”

Not found (unknown id/key, or a privacy-blocked auction — a 403 would assert existence).

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
}