Authentication
Authenticate Data API requests with an agency key, a location secret key or a scoped key, and bind a location to scope the data you receive.
Authentication
The Data API accepts three key types, all passed as a bearer token in the Authorization header.
| Key type | Prefix | Scope |
|---|---|---|
| Agency key | ak_ | All locations linked to the agency |
| Location secret key | sk_ | A single location |
| Scoped key | mcp_ | Only the routes its scopes grant — people:read, events:read, sessions:read, replays:read, exceptions:read, heatmaps:read, bigquery_export:read here |
Bearer token. Format: Bearer ak_... for an agency key, or Bearer sk_... for a location secret key.
These are server-side credentials — never embed a key in browser-side JavaScript, public repositories, or logs. The API does send CORS headers (so first-party surfaces like the Builder embed, which is handed a key deliberately, can read it from a browser), but that is a compatibility measure: anything holding your key can call this API from anywhere, with or without a browser.
Binding a location
Data is isolated per location, and the location is derived entirely from the auth context — never from a resource id in the path.
- Location secret keys (
sk_) resolve their location automatically. No extra parameter is needed. - Agency keys (
ak_) must name a location on every request, using either thelocation_idquery parameter or theX-Location-Idheader. The location must be linked to the agency, or the request returns403 location_not_linked.
Location to scope the request to. Required for agency keys on every route except /export.
Alternative to the location_id query parameter for agency keys.
If an agency key calls a location-scoped route without binding a location, the request returns 400 location_required.
Examples
# Location secret key — location is implicit
curl https://mythic-analytics.gulp.workers.dev/client/v1/data/people \
-H "Authorization: Bearer sk_YOUR_SECRET_KEY"
# Agency key with the location in a header
curl https://mythic-analytics.gulp.workers.dev/client/v1/data/people \
-H "Authorization: Bearer ak_YOUR_AGENCY_KEY" \
-H "X-Location-Id: acme-retail"
# Agency key with the location as a query parameter
curl "https://mythic-analytics.gulp.workers.dev/client/v1/data/people?location_id=acme-retail" \
-H "Authorization: Bearer ak_YOUR_AGENCY_KEY"
The /export exception
The /export route reports agency-wide BigQuery export status and does not require a bound location. It requires an agency (ak_) key — secret keys return 403 agency_required.
HIPAA locations
Locations with HIPAA mode enabled are blocked from the Data API. Any request scoped to such a location returns 403 hipaa_restricted, regardless of key type.