Aller au contenu
HitKeep
Selectionner la langue
Selectionner le thème
GitHub
Démarrer gratuitement dans le Cloud

HitKeep API Client Tokens for Analytics

Ce contenu n’est pas encore disponible dans votre langue.

You want to pull analytics data into a custom dashboard, a CI pipeline, or an internal tool without using your main session cookie. API Clients let you create named, scoped tokens that authenticate against the HitKeep REST API using a standard Authorization: Bearer header.

For interactive integrations and OAuth-capable MCP clients, OAuth avoids copying tokens. Integration → OAuth clients registers a public PKCE application for a team, while Connected applications in the header user menu manages the OAuth access you personally approved. Neither page creates the manual bearer tokens described here. Existing API-client tokens remain supported and do not need to be replaced when upgrading.

HitKeep supports two ownership modes:

  • Personal API clients live under Integration → API and belong to one user.
  • Team API clients live under Administration → Team → API clients and belong to the team itself, so they survive when an individual user leaves the team.
HitKeep Integration API page for managing personal bearer tokens
Integration → API: create and revoke personal bearer tokens for programmatic access.
HitKeep team API clients page for managing shared bearer tokens
Administration → Team → API clients: team-owned bearer tokens for shared integrations and automation.

Use a personal API client when the token is just for you or tied to your own user account.

Use a team API client when the token powers a shared integration such as:

  • a CI export job
  • a shared Grafana dashboard
  • a reporting sync owned by the marketing or product team

Team API clients are the safer default for automation because they are not deleted when the original creator leaves the team. Team clients have no site access until a team owner or admin adds explicit site grants.

A personal token cannot retain permissions its owner no longer has. Effective access is the intersection of the explicit delegation and the current owner authority, including MCP, server ingest, and deferred AI tools. Rotation, expiry, or revocation also invalidates previously captured tool contexts. Team credentials remain independent of an individual creator and require their explicit team/site grants.

  1. Open Integration → API in the HitKeep dashboard.
  2. Click New API Client.
  3. Give the client a descriptive name (e.g., grafana-reader, ci-exporter).
  4. Copy the generated token immediately — it is shown once.

API reference:

Site access is explicit: a personal client with no site grants can still be useful for allowed instance/admin APIs, but it cannot read analytics, use MCP site tools, or ingest site data until you add a site role grant.

  1. Open Administration → Team → API clients.
  2. Create a token and grant it access to one or more sites in the current team.
  3. Copy the generated token immediately; it is shown once.

API reference:

Pass the token as a Bearer token in the Authorization header on any API request:

For example, any authenticated site stats request in the API reference can be called with a bearer token:

This is suitable for server-to-server use. Site-scoped endpoints require a matching site_roles grant on the token; an instance/admin role alone does not grant access to site analytics, MCP tools, or ingest endpoints. Do not expose tokens in client-side JavaScript. Server clients should send the bearer token and normal API headers without adding browser-only Sec-Fetch-* or Origin headers.

Send exactly one JSON value per request body and use the field names shown in the API reference. HitKeep treats object member names as case-sensitive, rejects duplicate names, and rejects invalid UTF-8 instead of replacing malformed bytes. Operations with a closed request schema also reject unknown members; forward-compatible operations may ignore unknown members, so do not use that behavior as a feature-detection mechanism.

These checks remove ambiguous inputs before authentication, validation, persistence, or forwarding. Responses use Go’s v2 JSON field-omission semantics: omitempty is based on the encoded JSON value, so zero numbers and booleans can remain present. HitKeep additionally keeps deterministic object output, null for nil collections, and HTML- and JavaScript-safe string escaping.

HitKeep built-in API reference with interactive endpoint documentation
The built-in API reference is available on your own instance, so teams can inspect operations and test authenticated flows without leaving their deployment.

The optional Official MCP Server accepts these API client bearer tokens and scoped OAuth access tokens for its configured MCP resource. It does not accept dashboard cookies. The instructions below use a manual API-client token.

Connect your MCP client to the configured Streamable HTTP endpoint and send:

Authorization: Bearer <hitkeep-api-client-token>

The MCP server applies API rate limiting, tenant-aware analytics store resolution, and site permissions. A token can only query sites where it has site.view.

Use team API clients for shared assistants and scope them only to the sites the assistant needs. For the full assistant setup, pair the token and MCP endpoint with the HitKeep Agent Skills.

Chart annotations accept API client tokens, so a deployment pipeline can add a note for every production release.

TaskToken scope
List annotationssite.view for the site
Create, update, or delete annotationssite.manage_annotations for the site (owner, admin, or editor site role)

The MCP tool hitkeep_get_annotations is read-only and needs only site.view.

Saved Opportunity Recommendations use the same site permission model as the dashboard.

TaskToken scope
List saved Opportunitiessite.view for the site
Generate or regenerate Opportunitiessite.manage_data for the site
Save, dismiss, or mark donesite.manage_data for the site

Use this when an internal workflow needs to pull saved recommendations into a reporting system or trigger regeneration after a data import. The API returns translation keys, interpolation params, cited evidence, and detector metadata. It does not return raw prompts or raw provider responses.

Server-side pageview and event ingest uses API client tokens. Give the token site.manage_data for each site it writes to.

Use this for backend forwarding, CMS plugins, and historical replay jobs that submit original timestamp, url, visitor_ip, and user_agent values.

Guide:

API reference:

AI crawler fetch ingest also uses API client tokens. Give the token site.manage_data for the target site and send matching crawler request metadata to:

POST /api/sites/{site_id}/ingest/ai-fetch
Authorization: Bearer <hitkeep-api-client-token>

Use this for CloudFront log forwarding, origin log forwarding, or app-server middleware that can see crawler requests. The browser tracker cannot reliably capture AI crawlers because most crawler requests do not run JavaScript.

Guide:

API reference:

Use the generated reference for the full lifecycle:

Only team owners and admins can manage team API clients.

  • Use one token per integration so you can revoke granularly.
  • Rotate tokens periodically with the roll-token action. The old token stops working immediately and the new token is shown once.
  • Store tokens in environment variables or a secrets manager, never in source code.
  • HitKeep does not store tokens in plain text — only a hashed form is retained after creation.
  • Prefer team API clients for long-lived automation owned by a team instead of a single person.
  • Grant API clients access only to the sites they actually need.