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.
• Expiry. On the sandbox, a key issued since 2026-10-30 expires after 90 days unless we set another date. We tell you the date at handover. On production, keys do not expire by default yet; production gets the same rule (365 days by default) with its next release, and any production key we issue tells you its date if it has one. An expired key answers 401 exactly like a revoked one, with no warning beforehand — see Expiry and rotation.
• 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 owns your bookings and webhook subscriptions and holds your venue grants. Rate limits apply per key (see Rate limits).

If you lose a key, or think it has leaked, email hello@venuesetu.com. We revoke it at once and issue a replacement through the handover below. 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 by emailing hello@venuesetu.com, and name one engineer who will receive keys.
2. We register your partner identity on the sandbox host, create a key for it and grant venues.
3. After certification, we repeat that on production — a different key, handed over the same way.

Handover

• We send the key to your named engineer as a one-time secret link (a link that opens once and then expires). We never send a key by email, chat or ticket.
• We tell your engineer separately, by email, to expect the link. That email never contains the key.
• Open the link promptly and store the key in your secret manager. If the link was already opened or has expired when you try it, tell us: we revoke that key and send a new one.
• We record which engineer received which key, and when.

Expiry and rotation

The API gives no warning before a key expires, and we send no automated reminders. Rotation is a manual step on our side:

1. About 30 days before a key expires, we contact your named engineer.
2. At least 14 days before expiry, we hand over a replacement key as above. Both keys work in the meantime.
3. You switch to the new key and tell us.
4. We check your traffic uses the new key, then revoke the old one.

Track the expiry date on your side too. You can ask for a rotation at any time.

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.
• Reads and purchases scoped to a venue (availability, active packages, membership lookup, price preview) at a venue you are not granted: 403 VENUE_NOT_AUTHORIZED; a package purchase there answers 404, like an unknown package.
• A resource_id the venue does not have (another venue's type, or a court number above the venue's count): 400 SLOT_NOT_AVAILABLE, and no inventory is created.
• Operating on a hold/booking another partner owns: 403 UNAUTHORIZED (ownership is checked first). Reading another partner's booking answers 404 BOOKING_NOT_FOUND.

If you believe a venue should appear and it does not, email hello@venuesetu.com — 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.

Every error code, with its statuses, is listed in Errors.

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 (hello@venuesetu.com) 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.