Quickstart

This walks you from zero to receiving your first webhook in under 10 minutes. Goal: a script that fetches your tenant info and an HTTPS endpoint that receives signed events when something changes.

1. Generate an API key

From the admin dashboard, go to app.tattoobooking.com/api-keys and click New API key. Pick the scopes your integration needs (the default set works for most flows). The key is shown only once on creation — save it to your password manager immediately.

Keys look like tb_live_sk_.... For local testing, you can also generate a test-mode key (tb_test_sk_...) — it hits the same production endpoints but is rate-limited more aggressively and tagged in the audit log.

Plan requirement. API keys are unlocked at the Solo plan ($49/mo) and up. Light (free) tenants need to upgrade first.

2. Set your environment

# .env
TB_API_KEY=tb_live_sk_xxxxxxxxxxxxxxxxxxxx
TB_BASE_URL=https://api.tattoobooking.com

3. Make your first request

The /v1/me endpoint returns the identity behind your key (tenant, scopes, plan). Use it as a connection-test and to introspect what the key can do.

curl $TB_BASE_URL/v1/me \
  -H "Authorization: Bearer $TB_API_KEY"

You'll get back something like:

{
  "object": "me",
  "tenant_id": "ten_abc...",
  "tenant_name": "Acme Tattoo Studio",
  "plan_slug": "solo",
  "api_key": {
    "id": "key_xyz...",
    "name": "Integration Key",
    "scopes": ["read:clients", "write:clients", "read:appointments", "..."],
    "rate_limit_tier": "standard"
  }
}

4. List your clients

curl "$TB_BASE_URL/v1/clients?limit=5" \
  -H "Authorization: Bearer $TB_API_KEY"

Returns a cursor-paginated list. To page forward, follow the next_cursor field. See Pagination for the full pattern.

5. Subscribe to webhooks

Pick an HTTPS URL on your server that can receive POST requests. For local development use a tunneling tool like ngrok to get a public URL pointing at localhost.

curl -X POST $TB_BASE_URL/v1/webhook_endpoints \
  -H "Authorization: Bearer $TB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-tunnel.ngrok.io/webhooks/tattoobooking",
    "events": ["appointment.created", "lead.created", "form_submission.created"],
    "description": "Local dev — quickstart"
  }'

The response includes the signing secret. Save it — you'll need it to verify signatures, and it's shown only once.

{
  "endpoint": {
    "id": "whe_<uuid>",
    "url": "https://your-tunnel.ngrok.io/webhooks/tattoobooking",
    "status": "ACTIVE",
    "events": ["appointment.created", "lead.created", "form_submission.created"]
  },
  "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

6. Trigger an event

From the admin dashboard, create a new client or book a test appointment. Within a few seconds your endpoint will receive a POST that looks like:

{
  "id": "evt_xxxxxxxx",
  "type": "appointment.created",
  "api_version": "v1",
  "tenant_id": "ten_abc...",
  "created_at": "2026-05-27T15:00:00.000Z",
  "data": {
    "appointmentId": "apt_xxx...",
    "artistId": "art_xxx...",
    "startDateTime": "2026-06-15T14:00:00.000Z",
    "endDateTime": "2026-06-15T17:00:00.000Z",
    "status": "SCHEDULED",
    ...
  }
}

7. Verify the signature

Every delivery includes a TattooBooking-Signature header. Verify it before trusting the payload — see Webhooks for the full code sample.

Where to go next

• Browse the API reference — every endpoint and every field documented with examples.
• Read Webhooks for the full signing, retry, and replay docs.
• If you're building an integration for OTHER TattooBooking tenants (not just your own), read OAuth 2.0 — that's the auth model you want, not API keys.