Authentication

Every request carries your API key as a bearer credential:

Authorization: Bearer gck_live_<prefix>.<secret>

Requests are scoped to the listings your key’s owner owns or writer-manages. The three failures you’ll meet are 401, 403, and 404. Each returns the same envelope: { "code": ..., "message": ..., "correlationId": ... } - branch on the stable code, never on message. See the full error-code catalog for every code.

401 - invalid or missing key

A missing, malformed, revoked, or expired key returns 401 with code: "UNAUTHENTICATED". (This example needs no real key.)

# EXPECT: 401
curl -sS -o /dev/null -w '%{http_code}' \
  -H "Authorization: Bearer gck_live_deadbeef.invalid" \
  "$PUBLIC_API_BASE/v1/listings"

403 - read-only key on a write

A read-only key may read but not write. A write with a read-only key returns 403 with code: "FORBIDDEN". Mint or rotate a read-write key for writes.

# EXPECT: 403
curl -sS -o /dev/null -w '%{http_code}' \
  -X POST \
  -H "Authorization: Bearer $GCK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listingId":"00000000-0000-0000-0000-000000000000","checkInDate":"2026-01-01T00:00:00Z","checkOutDate":"2026-01-02T00:00:00Z","numberOfGuests":1}' \
  "$PUBLIC_API_BASE/v1/forms"

404 - out of scope or unknown

An id outside your key’s scope, or one that doesn’t exist, returns 404 with code: "RESOURCE_NOT_FOUND". The two cases are indistinguishable - the API never discloses the existence of resources you can’t reach.

# EXPECT: 404
curl -sS -o /dev/null -w '%{http_code}' \
  -H "Authorization: Bearer $GCK_KEY" \
  "$PUBLIC_API_BASE/v1/listings/00000000-0000-0000-0000-000000000000"