---
title: "Connect HitKeep Integrations With OAuth | HitKeep"
description: "Authorize WordPress and MCP clients for explicit HitKeep teams, sites, scopes, and resource audiences while preserving existing API clients."
canonical: "https://hitkeep.com/guides/security/oauth/"
---

# Connect HitKeep Integrations With OAuth

OAuth lets an integration connect to HitKeep without asking you to create and paste an API token. Use it when your HitKeep instance exposes OAuth discovery and the client supports this flow. Existing API-client credentials remain supported for scripts and clients without OAuth.

## Release availability

HitKeep **2.15.0** supports scoped API-client bearer tokens and OAuth connections for MCP, with **Integration → Assistants** setup. OAuth connections require an instance that exposes OAuth discovery and a compatible client; a screenshot or client setup link does not establish that an instance has that capability. See [current release facts](https://hitkeep.com/reference/facts-and-limits/) and [manual API clients](https://hitkeep.com/guides/security/api-clients/).

## Approve a connection

For analytics assistants, open **Integration → Assistants** (`/integration/assistants`) to copy the canonical MCP URL and find setup guidance. Ordinary viewers can read that guidance without permission to administer client registrations.

Choose your canonical HTTPS HitKeep instance in the integration, sign in through the normal HitKeep account flow, and explicitly approve the connection. Signup, email verification, SSO, MFA, and managed-cloud checkout preserve a bounded continuation; completing them does not approve the integration automatically.

Consent selects one team, explicit sites, the requested scopes, and one resource audience. Open the user menu in the header and choose **Connected applications** to review your grants. Select an application row to open its details dialog, review its sites, scopes, and resource, or revoke the connection. A grant cannot retain access after your underlying site permission is removed.

![Connected application details dialog showing its team, selected sites, scopes, and resource](https://hitkeep.com/_astro/oauth-application-details.Dff9osOA_ZxrMMP.webp)

Select an application in Connected applications to review or revoke your own connection.

| Scope | Permitted use |
| --- | --- |
| sites:read | Discover granted sites and minimal metadata. |
| analytics:read | Read approved aggregate analytics and the read-only MCP surface. |
| tracking_domains:read | Discover eligible active tracking endpoints without domain administration data. |
| ingest:write | Submit authenticated server-side events and pageviews to granted sites. |

Scopes do not replace HitKeep permissions. Every request must satisfy its scope, explicit site consent, current team/site ownership, and the user’s current authority. OAuth does not open dashboard administration, billing, exports, token management, or writes through MCP.

## Resource binding and discovery

For an issuer `https://analytics.example.com/hitkeep`, the API resource is `https://analytics.example.com/hitkeep/api`. The MCP resource uses the instance’s enabled configured MCP mount under the same issuer. Tokens for one resource are rejected by the other.

The authorization-server metadata document is at:

```
https://analytics.example.com/.well-known/oauth-authorization-server/hitkeep
```

The API protected-resource metadata document is at:

```
https://analytics.example.com/.well-known/oauth-protected-resource/hitkeep/api
```

Use the resource’s advertised metadata and authentication challenge for MCP rather than assuming its mount is `/mcp`. Preserve these exact metadata routes in reverse proxies for path-prefixed deployments. Custom tracking hosts remain limited to browser tracking; use the canonical instance for OAuth, REST, MCP, refreshes, and server-side ingest.

### Check instance support

Start with the canonical MCP endpoint supplied by the operator or, where available, **Integration → Assistants**. An unauthenticated request to an OAuth-enabled MCP endpoint returns a `WWW-Authenticate` challenge with a `resource_metadata` URL. Fetch that document and verify that `resource` exactly matches the intended MCP URL, including its prefix and custom mount. Follow its `authorization_servers` entry to the issuer’s metadata; HitKeep advertises PKCE `S256`, public-client authentication `none`, and CIMD support.

For the example issuer above with MCP mounted at `/mcp`, the MCP metadata URL is `https://analytics.example.com/.well-known/oauth-protected-resource/hitkeep/mcp`. The prefix belongs after `oauth-protected-resource`, not before `/.well-known`. A missing document does not identify the deployed binary or explain why OAuth is unavailable; check the canonical URL, proxy routes, and operator configuration.

OAuth initialization requires a valid canonical HTTPS `public-url`, a valid public-client registry, the configured browser signing key, and a control-plane store. Invalid issuer, registry, or signing configuration leaves OAuth unavailable while ordinary login and API-client authentication remain separate. MCP OAuth additionally requires MCP to be enabled and requests to reach the authoritative leader. Disabling MCP removes its OAuth resource; it does not disable the REST API OAuth resource. See the [configuration reference](https://hitkeep.com/reference/configuration/) for released settings.

Assistant OAuth grants authorize integration access. They do not configure a model provider or enable Ask AI. [AI model configuration](https://hitkeep.com/guides/admin/ai-model-configuration/) controls the provider route and credentials; [Ask AI](https://hitkeep.com/guides/analytics/ask-ai/) uses the signed-in user’s site permissions and an internal tool bridge.

## Client developers

HitKeep embeds Ory Fosite with DuckDB storage in the existing binary. Supported public clients use Authorization Code with mandatory PKCE S256, exact registered redirect matching, and `token_endpoint_auth_method=none`. A client can use a team registration, an operator-controlled registration, or a validated public HTTPS Client ID Metadata Document (CIMD). Team registrations require HTTPS callbacks. Operator-configured clients and validated HTTPS-fetched CIMD clients may declare native HTTP loopback callbacks under the rules below. Metadata fetching rejects private networks and redirects and bounds response size, time, and cache growth. Client metadata must support the public `none` authentication method; HitKeep rejects client secrets and client assertions. CIMD identifies a client without a registration endpoint; HitKeep does not expose Dynamic Client Registration (DCR).

Use the instance’s advertised authorization, token, and revocation URLs. Send `resource` on code exchange and refresh. A code exchange may omit `redirect_uri`; when supplied, it must exactly match the callback selected during authorization. Empty or changed values are rejected, and the correct PKCE verifier remains required. Keep access and refresh tokens in the integration’s secure credential store; refresh tokens rotate, and replay revokes the containing grant. A lost rotation response requires a new authorization. Codes and access tokens are short-lived; the server stores credential hashes, not reusable token values.

At authorization, `state` may be omitted. If supplied, it must be nonempty, no longer than 1024 bytes, and is returned unchanged. Keep your client’s callback correlation checks. `redirect_uri` may be omitted only when the validated client has exactly one registered callback; HitKeep selects and binds that callback to the code. An explicit empty or unregistered callback, or omission with multiple callbacks, is rejected.

Server-side ingest with OAuth additionally requires a `site_id` matching both the explicit grant and the URL-resolved site. Existing API-client ingest payloads do not require that new field. The integration API exposes granted sites, eligible tracking domains, and a fixed seven-day aggregate preview; it does not expose raw analytics or domain verification secrets.

The runtime [API reference](https://hitkeep.com/api/) is the endpoint and payload contract. MCP remains optional, read-only, aggregate-only, and leader-only. Protocol support does not imply that a provider has approved a Claude or ChatGPT marketplace listing.

## Manage OAuth clients for your team

Team owners and administrators with `team.manage_api_clients` can manage public OAuth registrations for the active team at **Integration → OAuth clients** (`/integration/oauth-clients`).

1. Select the team that owns the integration and open **OAuth clients**.
2. Choose **Register client**, enter a name, and optionally add the application’s public HTTPS website.
3. Enter each exact HTTPS callback URL on its own line, then save. Callbacks cannot contain wildcards, credentials, fragments, or whitespace; register between one and sixteen callbacks.
4. Copy the generated, immutable client ID into the integration. These public Authorization Code clients require PKCE S256 and `token_endpoint_auth_method=none`; no client secret is generated or accepted.

![Register client dialog with a display name, optional HTTPS application website, and an exact HTTPS callback URL](https://hitkeep.com/_astro/oauth-client-registration.DLoJQFfA_ZANwR3.webp)

Enter each exact HTTPS callback on its own line. Public PKCE clients do not receive a client secret.

A team can have up to 128 active registrations. Team registrations can authorize only that team’s sites, subject to each user’s explicit consent and current permissions.

![OAuth client details dialog showing its public client ID, website, and exact HTTPS callback URL](https://hitkeep.com/_astro/oauth-client-details.CLVkA2MV_Z10MxL8.webp)

Select an OAuth client to review its registration details. Choose Edit to open the registration form.

Select a registration row to open its details dialog, then choose **Edit** to change its name, application website, or callback URLs. The row actions also offer details, editing, and revocation. Saving an edit invalidates existing grants and pending consent for the previous registration version. Users must restart authorization and approve a new connection. Revoking a registration stops new authorizations and revokes its existing grants.

These are three separate controls:

| Control | Where to manage it | What it does |
| --- | --- | --- |
| Team OAuth registration | Integration → OAuth clients | Gives an application a public client ID and approved callbacks; it grants no analytics access by itself. |
| Personal OAuth grant | Header user menu → Connected applications | Records the team, sites, scopes, and resource you approved; disconnecting revokes your own grant. |
| Manual API-client token | Personal Integration → API or team administration | Creates a bearer credential you copy into a script or client, with explicit delegated site roles. |

Registering a client does not replace manual API-client tokens or create a personal grant. Clients identified by HTTPS metadata documents and operator-configured registrations are managed separately.

## Pre-register an operator-controlled client

HTTPS Client ID Metadata Documents work without an operator entry. For a client needing explicit registration, set `oauth-clients` in the existing HitKeep YAML configuration file to a JSON array of public client metadata, then restart the instance:

```
oauth-clients: >-
  [{"client_id":"reporting-client","client_name":"Internal reporting","redirect_uris":["https://reporting.example.com/callback"],"token_endpoint_auth_method":"none"}]
```

The configuration registry uses the same exact-redirect and public-client validation as authorization. Duplicate identities, unknown fields, client secrets, and unsafe hosted redirects are rejected. These instance-level registrations remain operator-controlled and are separate from team registrations in the dashboard. Configuration edits apply to new authorizations; use grant revocation to disconnect an existing connection. An invalid registry disables OAuth with a bounded operator warning; it does not disable ordinary login or legacy API clients.

### Native loopback callbacks

Operator-controlled registrations and clients identified by validated public HTTPS CIMD may declare an HTTP callback on `localhost` or an IP-literal loopback host such as `127.0.0.1` or `[::1]`. The declaration may omit its port. A native client may choose its listener port at authorization; only the port may vary. The scheme, exact declared hostname spelling, escaped path, and raw query must remain unchanged. `localhost`, `127.0.0.1`, and different IPv6 spellings are not interchangeable.

Arbitrary HTTP destinations, wildcard hosts, credentials, fragments, and malformed, empty, zero, or out-of-range explicit ports are rejected before callback matching. HTTPS callbacks still require an exact match. Team registrations in the dashboard remain HTTPS-only; they do not inherit this native exception.

The callback is a browser destination, not a metadata-fetch target. CIMD retrieval still requires public HTTPS and retains its private-network, DNS-pinning, TLS, redirect, and response-bound protections. Supporting a local callback does not allow HitKeep to fetch metadata from localhost or another private address.

Send the actual listener callback in the authorization request. The code binds that selected callback; if `redirect_uri` is also sent during code exchange, it must match the selected request-time callback exactly, including the port.

## Upgrade and recovery

Existing users, compact role grants, and API-client tokens are retained. Personal credentials use current owner authority as well as their delegation; team credentials retain explicit team/site grants. No credential replacement or destructive ACL conversion is required.

OAuth adds control-plane tables. Preserve normal backups and migration checks when changing server versions. Reverting to an older binary disables OAuth functionality while retaining the additive data; qualify the specific downgrade before using it as an operational rollback. Older user-deletion code can leave unusable OAuth rows, which do not authorize a missing user. This is not a promise that an arbitrary older binary can safely restore every newer database.

An unsupported HTTP issuer or unavailable authoritative node does not silently switch an OAuth credential to dashboard-cookie authentication. Existing non-OAuth login and API-client workflows remain separate. If consent expires or the service is unavailable, return to the integration and retry authorization.

## Related

- [WordPress](https://hitkeep.com/guides/integrations/wordpress/)
- [MCP](https://hitkeep.com/guides/integrations/mcp/)
- [API clients](https://hitkeep.com/guides/security/api-clients/)

[Previous API clients](https://hitkeep.com/guides/security/api-clients/)[Next Two-factor authentication](https://hitkeep.com/guides/security/two-factor-authentication/)