API Clients

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.

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

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

curl -X POST https://your-hitkeep.example/api/user/api-clients \
  -H "Content-Type: application/json" \
  -b "hk_token=YOUR_SESSION_COOKIE" \
  -d '{"name":"grafana-reader"}'

Response:

{
  "id": "01JFKQ...",
  "name": "grafana-reader",
  "token": "hk_live_abc123..."
}

Using a Token

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

curl https://your-hitkeep.example/api/sites/{site_id}/stats \
  -H "Authorization: Bearer hk_live_abc123..."

This works for all authenticated API endpoints and is suitable for server-to-server use. Do not expose tokens in client-side JavaScript.

Managing Tokens

# List all clients
curl https://your-hitkeep.example/api/user/api-clients \
  -b "hk_token=YOUR_SESSION_COOKIE"

# Rename a client
curl -X PUT https://your-hitkeep.example/api/user/api-clients/{client_id} \
  -H "Content-Type: application/json" \
  -b "hk_token=YOUR_SESSION_COOKIE" \
  -d '{"name":"renamed-client"}'

# Delete a client (immediately revokes the token)
curl -X DELETE https://your-hitkeep.example/api/user/api-clients/{client_id} \
  -b "hk_token=YOUR_SESSION_COOKIE"

Security Best Practices

• Use one token per integration so you can revoke granularly.
• Rotate tokens periodically by deleting the old client and creating a new one.
• 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.

Related

• REST API Reference
• Two-Factor Authentication
• Configuration Reference

Need per-token scope restrictions or team-level token management? These are planned features for HitKeep Cloud →.