Authentication and keys
One key, one account, one set of things it can reach.
Making a key
Keys are made in Studio, under your business account, not through the API. A key looks like vnd_live_ followed by 48 hex characters, and you send it as Authorization: Bearer <key> on every request.
The first call worth making is GET/v1/me. It answers what the key is attached to and what it may do, which is the quickest way to tell a working key from a mistyped one.
Who a key belongs to
Every key belongs to one principal, and every response is filtered to it. A principal is one of three things, and today two of them can hold a key.
- An organiser reaches its own events and the confirmed orders against them.
- A venue reaches the events happening at its address, and can subscribe to webhooks for them.
- A professional cannot hold a key yet. There is nothing for one to read until the profile and offerings endpoints exist, so Venued refuses to mint one rather than issue a key that reaches nothing.
What a key may do
Permission is the scope and the kind of account together, never the scope alone. The same scope string means different things to different principals: events:read means my events to an organiser and the events at my address to a venue.
Some combinations cannot be made at all. A venue key cannot be given events:write or orders:read, because a venue does not own the events booked into it, and the buyers’ names and email addresses on an order are the organiser’s business rather than the building’s.
Limits
600 reads and 120 writes a minute, counted in a fixed 60-second window. GET and HEAD are reads; POST, PATCH and DELETE are writes. Going over returns 429.
When something is refused
Every error carries a stable code and the id of the request that failed, both in the body and as an X-Request-Id header. Quote that id if you ask us about it and we can find the exact request.
401 unauthorized— the key is missing, mistyped or revoked.403 forbidden— a real key that is not allowed to do this.400 unsupported_parameter— a query parameter we do not know. We refuse rather than ignore it, because a filter that looks applied but is not is how a job quietly ships every row it meant to leave out.429 rate_limited— over the limit above.