Authentication

Authentication model

Administrative endpoints and private site statistics require a valid Firebase ID token passed in the standard Authorization header:

Authorization: Bearer <FIREBASE_ID_TOKEN>

Key credential rules:

• Totallytics does not use static API keys or server-to-server service account JSON credentials.
• Simple Analytics credentials cannot authenticate Totallytics API calls. They are only used as source configuration for historical imports.
• The client Firebase configuration API key is not an access token and will be rejected.

Obtaining an access token

Access tokens are short-lived JWTs (typically valid for approximately one hour).

To acquire your token for development or testing:

1. Sign in to your account at https://analytics.bitgate.dev/login.
2. Navigate back to this page (/docs/authentication).
3. Click Copy access token in the interactive panel. This copies your active Firebase ID token directly to your clipboard, refreshing credentials if necessary.

Using tokens in shell scripts

To prevent tokens from appearing in shell history or committed code, read the token into an environment variable using silent terminal input:

read -rsp "Totallytics ID Token: " TT_TOKEN && export TT_TOKEN

Pass the variable in the Authorization header of your API requests:

curl -sS --fail-with-body \
  -H "Authorization: Bearer $TT_TOKEN" \
  -H "Accept: application/json" \
  https://analytics.bitgate.dev/api/sites

Keep your token secure. Never include ID tokens in frontend client bundles, public repositories, or tracking script attributes.

Endpoint authorization rules

Different Totallytics endpoints enforce distinct access rules:

• Public collection (latest.js, simple.gif, POST /events): No token required. Collector CORS allows any origin; the payload’s registered hostname is checked separately.
• Public site reads (GET /api/sites/<hostname>, /api/sites/<hostname>/overview, and /api/sites/<hostname>/breakdown): No token required if the site owner has toggled site visibility to public in dashboard settings.
• Private site statistics: Requests without a token or with an invalid token return HTTP 401. Requests from an authenticated user who does not own the site return HTTP 403.
• Import source discovery requires sign-in. Site import jobs and their controls require the site owner, even if its dashboard is public.
• Site management (GET /api/sites, POST /api/sites, PATCH /api/sites/<hostname>, DELETE /api/sites/<hostname>): Requires a valid ID token belonging to the site owner.

Error responses

Authentication errors return standard JSON payloads accompanied by a Cache-Control: no-store header:

{
  "error": "sign in required"
}

Expected status codes:

• 401 Unauthorized: Token is missing, expired, or malformed.
• 403 Forbidden: Token is valid, but the account lacks permission for this site.
• 404 Not Found: The specified hostname does not exist.

Token expiration and retries

Tokens expire after about one hour. There is no long-lived automation credential or product token-refresh endpoint. For unattended jobs, provide an authenticated Firebase user session and handle token refresh before scheduling requests. For an existing signed-in session:

1. If a request returns HTTP 401, get a fresh ID token from your signed-in Firebase client session (user.getIdToken(true)) or use Copy access token again. The Firebase Admin SDK is not a refresh mechanism for a user’s ID token.
2. Re-run safe, idempotent requests (such as GET queries) using the new token.
3. Do not retry state-mutating requests (POST, DELETE) blindly without checking site state first.

Cross-Origin Resource Sharing (CORS)

Actual administrative and statistics responses (https://analytics.bitgate.dev/api/*) do not include CORS headers. The global OPTIONS handler does answer preflights, but that does not make the API cross-origin readable. Browser applications cannot query the API across origins, even for public sites.

Make all API calls from backend services, serverless functions, or from within the Totallytics web origin.

Review the Stats API Reference for querying overview charts and breakdowns.