Authentication

The TattooBooking API supports two auth schemes. Both use theAuthorization: Bearer <token> header — only the token format differs. The right one for you depends on whose data your integration accesses.

API keys — your own tenant

If your integration acts on YOUR OWN TattooBooking tenant (your studio syncing bookings to your accounting tool, your custom CRM dashboard, your AI phone agent answering your calls), use an API key.

Generate one at app.tattoobooking.com/api-keys. Keys have the format tb_live_sk_xxxxxxxxxxxxxxxxxxxx (production) or tb_test_sk_xxxxxxxxxxxxxxxxxxxx (test mode — same endpoints, tighter rate limits).

curl https://api.tattoobooking.com/v1/me \
  -H "Authorization: Bearer tb_live_sk_xxxxxxxx"

Key properties

Scopes. Each key has a list of scopes (e.g.read:clients, write:appointments). Calls to endpoints requiring scopes the key doesn't have return 403.
Rate-limit tier. standard (100/min default), pro (500/min on Studio+), or custom. Layered with a per-tenant 1000/min cap.
IP allowlist. Optional. If set, only the listed IPs can use the key.
Expiration. Optional. Keys auto-revoke at the configured time; you receive email warnings at 30/7/1 days out.

Rotation

Click Rotate on a key in the dashboard. The new key is shown once; the old key keeps working for 24 hours so you can update your secrets store without dropped traffic.

OAuth 2.0 — third-party integrations

If your integration acts on OTHER tenants' data (you're building a tool that any TattooBooking studio could connect to), use OAuth 2.0.

The high-level flow:

You register your app via super-admin (one-time, get back a client_id + client_secret).
Users of your app are redirected to /oauth/authorize with PKCE.
They approve at the consent screen on app.tattoobooking.com.
Your app exchanges the auth code for an access token + refresh token at /oauth/token.
You call /v1/* with the access token, refreshing as needed.

Full details in OAuth 2.0.

Which one do I need?

Use case	Auth
Your studio building an internal automation	API key
A reporting dashboard for your own data	API key
An AI phone agent answering your shop's calls	API key
Connecting your tenant to Zapier (single user)	OAuth (Zapier app uses it)
A SaaS product where any TattooBooking studio can sign up	OAuth
A marketplace integration like Square or Stripe	OAuth

Bad auth — error responses

All auth failures return 401 Unauthorized with a structured error body. See Errors for the full shape.

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json

{
  "type": "/errors/invalid_api_key",
  "title": "Invalid API key",
  "status": 401,
  "code": "invalid_api_key"
}

Common codes: missing_api_key, invalid_api_key, revoked_api_key, expired_api_key, inactive_api_key, ip_not_allowed (for API keys); invalid_access_token, revoked_access_token, expired_access_token, revoked_grant, app_suspended (for OAuth).