---
title: "HitKeep API Client Tokens for Analytics | HitKeep"
description: "Create scoped API tokens for programmatic access to HitKeep analytics data. Use bearer tokens for CI pipelines, dashboards, and integrations."
canonical: "https://hitkeep.com/guides/security/api-clients/"
---

# HitKeep API Client Tokens for Analytics

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.

HitKeep supports two ownership modes:

- **Personal API clients** live under **Settings → API Clients** and belong to one user.
- **Team API clients** live under **Administration → Team → Settings** and belong to the team itself, so they survive when an individual user leaves the team.

![HitKeep API clients — bearer token management](https://hitkeep.com/_astro/security-api-clients.ei6mcpl2_QPDJM.webp)

Settings → API Clients — create and revoke personal bearer tokens for programmatic access.

![HitKeep team API clients — shared token management in team settings](https://hitkeep.com/_astro/admin-team-api-clients.jqKu9cbi_1Q3QJB.webp)

Administration → Team → Settings — team-owned bearer tokens for shared integrations and automation.

## Choose the Right Ownership Model

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.

## Create a Personal Token

1. Open **Settings → API Clients** 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:

- [Create a personal API client](https://hitkeep.com/api/#tag/user/POST/api/user/api-clients)

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.

## Create a Team Token

1. Open **Administration → Team → Settings**.
2. Scroll to **Team API Clients**.
3. Create a token and grant it access to one or more sites in the current team.
4. Copy the generated token immediately — it is shown once.

API reference:

- [Create a team API client](https://hitkeep.com/api/#tag/teams/POST/api/user/teams/%7Bid%7D/api-clients)

## Using a Token

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:

- [Get site stats](https://hitkeep.com/api/#tag/sites/GET/api/sites/%7Bid%7D/stats)

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.

### JSON request rules

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](https://hitkeep.com/_astro/integration-api-reference.DUCKiK8A_1KpTUJ.webp)

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

## Use Tokens With MCP

The optional [Official MCP Server](https://hitkeep.com/guides/integrations/mcp/) uses the same API client bearer tokens. It does not accept dashboard cookies.

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](https://hitkeep.com/guides/integrations/hitkeep-agent-skills/).

## Use Tokens With Opportunities

Saved [Opportunity Recommendations](https://hitkeep.com/guides/analytics/opportunities/) use the same site permission model as the dashboard.

| Task | Token scope |
| --- | --- |
| List saved Opportunities | site.view for the site |
| Generate or regenerate Opportunities | site.manage_data for the site |
| Save, dismiss, or mark done | site.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.

## Use Tokens for Server-Side Tracking

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:

- [Server-Side Tracking](https://hitkeep.com/guides/tracking/server-side-tracking/)

API reference:

- [Ingest server-side pageview](https://hitkeep.com/api/#tag/ingest/POST/api/ingest/server/pageview)
- [Ingest server-side event](https://hitkeep.com/api/#tag/ingest/POST/api/ingest/server/event)

## Use Tokens for AI Fetch Ingest

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:

- [AI Fetch Ingest](https://hitkeep.com/guides/tracking/ai-fetch-ingest/)

API reference:

- [Ingest AI fetch record](https://hitkeep.com/api/#tag/sites/POST/api/sites/%7Bid%7D/ingest/ai-fetch)

## Managing Tokens

Use the generated reference for the full lifecycle:

- [List personal API clients](https://hitkeep.com/api/#tag/user/GET/api/user/api-clients)
- [Update a personal API client](https://hitkeep.com/api/#tag/user/PUT/api/user/api-clients/%7Bid%7D)
- [Roll a personal API client token](https://hitkeep.com/api/#tag/user/POST/api/user/api-clients/%7Bid%7D/rotate)
- [Delete a personal API client](https://hitkeep.com/api/#tag/user/DELETE/api/user/api-clients/%7Bid%7D)
- [List team API clients](https://hitkeep.com/api/#tag/teams/GET/api/user/teams/%7Bid%7D/api-clients)
- [Update a team API client](https://hitkeep.com/api/#tag/teams/PUT/api/user/teams/%7Bid%7D/api-clients/%7BclientId%7D)
- [Roll a team API client token](https://hitkeep.com/api/#tag/teams/POST/api/user/teams/%7Bid%7D/api-clients/%7BclientId%7D/rotate)
- [Delete a team API client](https://hitkeep.com/api/#tag/teams/DELETE/api/user/teams/%7Bid%7D/api-clients/%7BclientId%7D)

Only team **owners** and **admins** can manage team API clients.

## Security Best Practices

- 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.

## Related

- [REST API Reference](https://hitkeep.com/api/)
- [HitKeep Agent Skills](https://hitkeep.com/guides/integrations/hitkeep-agent-skills/)
- [Team Administration](https://hitkeep.com/guides/admin/teams/)
- [Opportunity Recommendations](https://hitkeep.com/guides/analytics/opportunities/)
- [Two-Factor Authentication](https://hitkeep.com/guides/security/two-factor-authentication/)
- [Configuration Reference](https://hitkeep.com/reference/configuration/)

[Previous Single sign-on (OIDC)](https://hitkeep.com/guides/security/single-sign-on/)[Next Two-factor authentication](https://hitkeep.com/guides/security/two-factor-authentication/)