Keys and scopes

Every API request is authenticated by a key or a user token. The key decides the tenant, the environment and what the request may do.

Type	Prefix	Sent as	Use
Secret	vk_live_, vk_test_	Authorization: Bearer	Server calls with full access to enabled products
Restricted	rk_live_, rk_test_	Authorization: Bearer	Server calls with chosen scopes
Publishable	vpk_live_, vpk_test_	Vabu-Publishable-Key	Browsers and apps
User token	JWT	Authorization: Bearer	A customer or staff member

Scopes

Scopes have the form {product}:{read|write}, for example events:read or streams:write. The scope platform:* covers keys, webhooks and integrations. A secret key has every scope for the products you have enabled. A restricted key has only the scopes you choose.

A request without the scope gets a 403 permission_error. A request for a product that is off gets 403 product_not_enabled.

Principals per endpoint

Each endpoint states which principals it allows. The API reference shows this under each operation.

Principal	Meaning
secret	A secret key
restricted:<scope>	A restricted key that has the scope
publishable	A publishable key
customer	A signed-in customer token
member:<permission>	A staff member with the permission
operator	Vabu platform staff, on the operator API

Which credentials each endpoint takes

Not every endpoint takes every credential. This is how the families split today. Each operation in the API reference also lists its own principals.

Endpoint family	Secret key	Restricted key	Publishable key	Signed-in user	Test mode
API keys and webhook endpoints	Yes	platform:read or platform:write	No	Team members with the right role	Yes
Customers (/v1/customers)	Yes	customers:read or customers:write	No	Team members with the right role	Yes
Access: entitlements and checks	Yes	access:read or access:write	No	No	Yes
Access: open, heartbeat and end a session	Yes	access:write (heartbeat and end also take streams:write)	Yes, with a customer token	No	Yes
Streams (/v1/streams/...)	Yes	streams:read or streams:write	Only POST /v1/streams/playback_tokens, with a customer token	No	Yes, on a simulated network
Public reads: GET /v1/events, GET /v1/events/{event}, GET /v1/plus/contents, GET /v1/plus/contents/{content}	Yes	events:read or streams:read	Yes	Not needed	Yes
Vabu ID sign-in (/auth/v1/...)	Not needed	Not needed	Optional, to sign in as your customer	Some routes need the access token	Yes
Everything else: booking, orders, tickets, organizer, creator, tenant staff and merch routes	Live keys, as before	Live keys, as before	No	Yes, with X-Tenant-Code	Not yet

For the last row, a request is made by a signed-in person (a Vabu ID or Payd ID token) with the tenant in the X-Tenant-Code header, or in Vabu-Tenant for a Vabu ID token. Some of these routes, such as browsing events and starting a checkout, need only the tenant header and no token. Test keys and publishable keys are refused on routes that do not list them, with 403 test_mode_unavailable or 403 insufficient_permissions. The product pages say which routes need what.

Lifecycle

• Create. The full key is shown once. Vabu OS keeps a hash and an 8-character prefix.
• Track. Each key records its last use, its creator, an optional expiry and an optional IP allowlist.
• Roll. Rolling creates a new key and sets an expiry on the old one: immediately, or up to 7 days later.
• Revoke. Revoking takes effect at once, and the change is audited. Your tenant owners get an email if a key was reported as leaked.

Keys are cached for up to 60 seconds for speed, and revocation clears that cache right away.