Authentication

Every API request must include a valid API key. Keys are scoped to a single Appspace and can be created in the API Keys section of your dashboard.

Key types

Type	Prefix	Use case
Publishable	tolk_pub_	Client-side code (browser, mobile app). Limited to read-only and event tracking endpoints.
Secret	tolk_sec_	Server-side code only. Full access to all endpoints including analytics reads and audience queries.

Danger

Never expose secret keys in client-side code, public repositories, or browser bundles. Secret keys grant full access to your Appspace data.

Sending your key

Include the key in the X-API-Key header (recommended):

curl -H "X-API-Key: tolk_sec_your_secret_key" \
  https://your-app.tolinku.com/v1/api/analytics/overview

You can also use the Authorization header with a Bearer prefix:

curl -H "Authorization: Bearer tolk_sec_your_secret_key" \
  https://your-app.tolinku.com/v1/api/analytics/overview

For browser environments that use navigator.sendBeacon (which cannot set headers), the key can be included in the JSON request body as an apiKey field:

navigator.sendBeacon(url, JSON.stringify({
  apiKey: 'tolk_pub_your_key',
  event_type: 'custom.page_view'
}));

Key scopes

Publishable keys can access:

• POST /v1/api/analytics/track (track custom events)
• POST /v1/api/analytics/batch (batch track events)
• GET /v1/api/banners (fetch smart banners)
• GET /v1/api/messages (fetch in-app messages)
• POST /v1/api/messages/:id/render-token (generate render tokens)
• GET /v1/api/messages/:id/render (render message HTML)
• All referral endpoints (/v1/api/referral/*)

Secret keys can access all of the above, plus:

• GET /v1/api/analytics/overview (aggregate metrics)
• GET /v1/api/analytics/funnel (conversion funnel)
• GET /v1/api/analytics/timeseries (daily breakdowns)
• GET /v1/api/analytics/campaigns (campaign breakdown)
• GET /v1/api/analytics/geo (geographic breakdown)
• GET /v1/api/analytics/events (raw event list)
• GET /v1/api/analytics/export (CSV export)
• All audience endpoints (/v1/api/audiences/*)

If a publishable key attempts to access a secret-only endpoint, the API returns:

HTTP 403
{
  "error": "This endpoint requires a secret API key. Publishable keys cannot access this resource."
}

Domain-resolved endpoints

Some endpoints do not require an API key at all. These are resolved by the hostname of the request (your Appspace’s subdomain or custom domain):

• GET /api/deferred/claim (claim deferred deep link by token)
• POST /api/deferred/signals (send device signals)
• POST /api/deferred/claim-by-signals (claim by fingerprint)
• POST /api/path (resolve a route by prefix)
• GET /api/banner/config (smart banner config for banner.js)
• GET /api/app/info (basic app info)

These endpoints use the /api/ path prefix (no /v1).

Key management

Create and manage API keys from the API Keys page in your Appspace dashboard. You can:

• Create multiple keys of each type
• Give each key a descriptive name (e.g. “Production Server”, “Mobile App”)
• Revoke keys instantly (revoked keys stop working immediately)

Tip

Use separate keys for different environments (development, staging, production) and different platforms (web, iOS, Android). This makes it easy to rotate or revoke a specific key without affecting other integrations.

Security best practices

• Store secret keys in environment variables or a secrets manager, never in source code.
• Rotate keys periodically. Create a new key, update your integration, then revoke the old key.
• Use publishable keys for all client-side code. They are designed to be safe for exposure.
• Monitor the API Keys page for unexpected usage patterns.