Authentication

Every Partner API request authenticates with an API key in a header:

x-api-key: <opaque key issued to you>

That is the only partner credential. There is no OAuth flow, no session cookie, and no partner_id you can send to act as someone else.

What the key is

• An opaque hex string, shown once when we create it. Store it like a password.
• Keys are opaque hex with no environment prefix in the string. Sandbox versus production is which host you call and which database the key was minted in.
• The key resolves to exactly one partner identity. That identity is used for rate limiting, booking ownership, webhook subscriptions, and venue authorization.

If you lose a key, we issue a new one and revoke the old. There is no retrieve-plaintext API.

How you get a key

Keys are issued by the CBMS platform team. This is not self-service.

1. You request sandbox access.
2. We create a key for your partner identity on the sandbox host and grant venues.
3. After certification, we repeat that on production — a different key.

Do not send a sandbox key to production, or a production key to sandbox. They will 401.

Partner identity

Your key is your partner. Fields named partner_id on hold, confirm, or webhook-subscribe bodies are ignored if you send them. Omit them.

Venue grants

A valid key does not mean every venue on the platform. Each partner is granted specific venues.

• No grants yet: GET /partner/venues returns 200 with an empty data array. That is waiting for onboarding, not a failure.
• A venue you are not granted: discovery returns 404 VENUE_NOT_FOUND (indistinguishable from a missing id, on purpose).
• Operating on a hold/booking you own at a venue that is no longer granted: 403 VENUE_NOT_AUTHORIZED.
• Operating on a hold/booking another partner owns: 401/403 UNAUTHORIZED (ownership is checked first).

If you believe a venue should appear and it does not, contact us — do not scrape ids.

Failures

HTTP	error	Meaning
401	UNAUTHORIZED	Missing, unknown, revoked, or expired key. We do not tell you which.
403	UNAUTHORIZED	Key is valid; this hold/booking belongs to another partner.
403	VENUE_NOT_AUTHORIZED	Key and ownership are fine; this venue is not granted.
429	RATE_LIMIT_EXCEEDED	Slow down. Honour Retry-After.

Branch on HTTP status and the error code together. UNAUTHORIZED is used for both bad credentials (401) and wrong owner (403).

Rate limits

Every key is limited to 60 requests per 60-second sliding window. Responses include:

X-RateLimit-Remaining: 49
X-RateLimit-Reset-Ms: 723

When exceeded:

HTTP/1.1 429
Retry-After: 12

{ "error": "RATE_LIMIT_EXCEEDED", "message": "Too many requests. Please wait before retrying.", "retry_after_seconds": 12 }

There are no self-serve tiers. If you need a higher burst (for example a daily availability warm-up), arrange it with the platform team before go-live.

What this documentation does not cover

Manager login, venue-operator dashboards, and platform-admin key minting are not Partner API. A partner key cannot reach them.