Authentication & Scopes

Every authenticated request carries a bearer token:

Authorization: Bearer tat_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Getting a key

A space leader creates a key from Settings → Integrations in the admin app. The plaintext is shown once, at creation, and stored only as a hash from then on — if it's lost, the fix is to create a new one, not to look the old one up.

Minting a key requires the space to be on a tier that includes API access (see Plans — this is an Enterprise feature today). A key can't be created otherwise, and an existing key starts returning feature_not_available if the space downgrades.

Three things worth knowing before you build around a key

• A key is not a user. It can't reach the admin API, can't sign in, and can't mint another key. Its whole reachable surface is this documentation.
• The granting leader's authority is checked on every request, live. If that person is removed from the space, every key they created stops working immediately — with no warning. Build for a key that can start returning 403 at any time.
• Keys expire. 90 days by default, configurable up to 365 at creation. GET /v1/me reports expires_at — check it and prompt for rotation rather than finding out when a request fails.

Keeping a key safe

Use it server-side only. A key embedded in a mobile app or a browser bundle belongs to whoever disassembles it, and it carries the whole space. If a browser needs to read a space, reach for the public surface instead — that's exactly what it's for.

Scopes

A key carries a fixed set of scopes, chosen when it's created. Call GET /v1/me at startup to discover them, rather than learning them one 403 at a time.

Scope	Grants
bookings:read	List and read bookings
bookings:write	Create, cancel, check in, record payment
bookings:override	Send allow_over_capacity / allow_policy_bypass on create
booking_types:read	Read the space's offering, schedules and pricing
booking_types:write	🚧 Not built yet
members:read	Roster, visit history, consent state
members:write	Add and update members
memberships:read	Plans and memberships
memberships:write	Assign, pause, cancel, record payment
content:read	🚧 Not built yet
webhooks:manage	🚧 Not built yet

Three scopes appear in the key-creation screen but grant nothing to call yet — see Roadmap for what's planned.

bookings:override is separate from bookings:write on purpose. Going over capacity or booking outside the usual window are decisions a host makes about their own space, so an integration has to be granted them explicitly rather than inheriting them along with ordinary write access.

A request missing a required scope gets a 403 with error.type of insufficient_scope — see Errors.

GET /v1/me

The way to check what a key can do, without guessing from a series of 403s:

curl https://api.tatiya.space/v1/me \
  -H "Authorization: Bearer $TATIYA_API_KEY"

Returns the key's label, its scopes, the space it belongs to, and expires_at. Call it once at startup and cache the result for the life of your process.