Authentication

Tiny Analytics uses two authentication models: bearer tokens for workspace APIs and source public keys for the public ingest API. Tiny does not use the starter template's basic-auth or OAuth flow.

Workspace apis

Most authenticated product APIs require:

Authorization: Bearer {access_token}
an organizationId query or body field when the action is workspace-scoped

Example:

curl "https://your-tiny-api/api/tracking-sources?organizationId=org_123" \
  -H "Authorization: Bearer {access_token}"

Workspace APIs include source management, permissions, team access, billing, support, and onboarding completion.

Public ingest

The public tracking endpoints identify the source through the path:

POST /api/ingest/v2/:publicKey/bootstrap
POST /api/ingest/v2/:publicKey/events

Example bootstrap request:

curl https://your-tiny-api/api/ingest/v2/pk_your_source_key/bootstrap \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "ingestVersion": 2,
    "sdkVersion": "0.2.0",
    "anonymousId": "vis_abc123",
    "sessionId": null,
    "userId": null,
    "page": {
      "url": "https://app.example.com/dashboard",
      "path": "/dashboard",
      "title": "Dashboard",
      "referrer": null
    },
    "context": {}
  }'

The public key is enough to route tracking traffic to the source, but it does not grant workspace-management access.

Tokens and keys

Use these rules to keep access safe:

keep bearer tokens on trusted server or authenticated client paths only
treat the source public key as install configuration, not as an admin credential
rotate public keys when you need to cut off an old install
expect 401 unauthorized for missing or invalid bearer tokens
expect 403 Forbidden when the user is authenticated but lacks the required workspace permission

For source setup, billing, support, and team management, always prefer the authenticated workspace API over direct database access.