API reference

Authentication

Public keys for browsers, server API keys for your backend, and how to rotate them.

There are three kinds of credential, plus a secret for the PostHog webhook.

CredentialLooks likeWhere it lives
Public keyphk_live_…Browser code. One per project.
Server API keytug_…Your server only. Covers the workspace.
Identity hashuserHashComputed on your server per user, sent from the page.
Webhook secretfwh_…PostHog's destination header. See PostHog.

Public key#

GET endpoints take it as the publicKey query parameter; POST endpoints as a publicKey field in the JSON body.

curl "https://tughq.com/api/v1/decisions/banner?publicKey=phk_live_…&userId=user_123"

Browser calls are checked against the project's Allowed origin. That stops other sites' browsers from using your key.

Server API keys#

Create keys under Settings, API keys. A key starts with tug_, is shown once, and works for every project in your workspace. Send it as Authorization: Bearer tug_…. Keys are included on every plan, trial too.

  • Required for GET /projects and every data subject request (/users/…, /suppressions/…).
  • Optional on /events, /identify, /decisions and /feedback (or pass apiKey to TugClient). The call still names its project with publicKey. The key must belong to that project's workspace; the Allowed origin check is skipped, and no userHash is needed.
curl "https://tughq.com/api/v1/projects" \
  -H "Authorization: Bearer $TUG_API_KEY"

Identity verification#

Your server signs each user ID with a per-project secret, and the page sends the result as userHash. Tug then refuses decisions and feedback for any other user. The full set-up is in Identity verification.

Rotating the public key#

The project page can rotate the public key. The previous key keeps working for 24 hours, so deploy the new one within that window.

  • PageOverviewGet started
  • PageQuick startGet started
  • PageConceptsGet started
  • PageScript tag (tug.js)Install
  • PageReactInstall
  • PageNode and serverInstall
  • PageIdentity verificationGuides
  • PageCounting and holdoutsGuides
  • PagePostHogGuides
  • PageEnvironmentsGuides
  • PageData requestsGuides
  • PageOperator consoleGuides