# Auth.md: HitKeep authentication

Use a scoped API-client bearer token created by the account owner at https://cloud.hitkeep.eu/integration/api-clients. Send it in the Authorization: Bearer header. Never send dashboard cookies to MCP or ask for passwords.

For OAuth, discover authorization server metadata at https://cloud.hitkeep.eu/.well-known/oauth-authorization-server. Use the existing authorization code flow with PKCE S256, a registered client ID or HTTPS client metadata document, the exact resource and least required scopes. The user signs in and explicitly consents to sites. Do not reuse tokens across resources. API resource metadata: https://cloud.hitkeep.eu/.well-known/oauth-protected-resource/api.

## Human-approved agent registration

HitKeep supports Auth.md user-claimed service_auth while AI is enabled. An assistant cannot create an account or access data before a human approves. Anonymous and provider identity-assertion registration are unsupported. Discover the actual endpoints and supported methods in authorization server metadata; identity_endpoint/register_uri and claim_endpoint/claim_uri are compatibility aliases for the same implemented routes.

1. Ask the user for their existing HitKeep account email and the access they want. Register using the discovered identity_endpoint:

~~~http
POST https://cloud.hitkeep.eu/agent/identity
Content-Type: application/json
~~~
~~~json
{"type":"service_auth","login_hint":"user@example.com","resource":"https://cloud.hitkeep.eu/api","scope":"sites:read analytics:read"}
~~~

   For Auth.md v0.5 clients, the same endpoint also accepts {"type":"identity_assertion","assertion_type":"verified_email","assertion":"user@example.com"} and returns registration_type=email-verification with the same claim ceremony. This compatibility name is only an email hint: it accepts no provider JWT or proof and grants no access. The current service_auth form is preferred. Both forms require the identical native human approval below.

   The response contains registration_id, claim_token, claim_token_expires, post_claim_scopes, and claim with user_code, verification_uri, expires_in, interval. It contains no access_token or identity_assertion. Save claim_token privately; never put it in a URL or log.
2. Show the user the six-digit claim.user_code and claim.verification_uri together. The user opens that link, signs in through HitKeep's normal sign-in/MFA/SSO, types the code on HitKeep, selects the team and sites, reviews every scope, and approves or denies. Their signed-in account email must match login_hint. Never ask the user to send their password, session cookie, or confirmation code back to the assistant. The link alone cannot approve access.
3. Poll https://cloud.hitkeep.eu/oauth/token with Content-Type: application/x-www-form-urlencoded and grant_type=urn:workos:agent-auth:grant-type:claim plus claim_token. Wait at least claim.interval seconds between polls. authorization_pending means keep waiting; slow_down means add five seconds to the interval. Stop on access_denied. Codes expire within ten minutes; the outer claim window is fifteen minutes, with at most five incorrect code submissions. Before the outer window expires, POST JSON {"claim_token":"<saved handle>","email":"user@example.com"} to https://cloud.hitkeep.eu/agent/identity/claim to replace a code and invalidate the old link; use claim_attempt from that response. After outer expiry or lockout, start a new registration.
4. After approval, one successful poll returns access_token, token_type=Bearer, expires_in, resource, scope, identity_assertion and assertion_expires. The claim handle is consumed once. Send the access token only to its resource in the Authorization: Bearer header. Access tokens last at most five minutes.
5. Until assertion_expires, refresh by POSTing form fields grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer, assertion=<identity_assertion>, and resource=https://cloud.hitkeep.eu/api to https://cloud.hitkeep.eu/oauth/token. No refresh_token is issued. The same service-signed assertion is intentionally reusable for this registration; it expires no later than one hour after approval. Every exchange rechecks current user, team, site and scope authority. The assertion cannot switch resources or expand scopes. Start a new human-approved registration after expiry.
6. To revoke one agent access token, POST token=<access_token>&token_type_hint=access_token to https://cloud.hitkeep.eu/oauth/revoke. That assertion remains usable until expiry. To disconnect the registration and revoke all its tokens and assertion refreshes, the human revokes its entry in Settings → Connected applications. While AI is disabled, agent registration and its credentials are disabled. Ordinary OAuth code clients keep their existing refresh rotation and credential-family revocation.

Use least privilege. For MCP, request its distinct configured resource with sites:read and analytics:read; MCP remains read-only. API scopes and operations are listed below and in OpenAPI. Billing requires explicit billing:write team consent and a separate human payment handoff; registration never performs a payment.

Public service information: [pricing](https://hitkeep.com/pricing), [terms](https://hitkeep.com/terms), [privacy](https://hitkeep.com/privacy). Integration support: https://github.com/HitKeep/hitkeep/issues. Self-hosted operators may set their own terms and pricing.

External assistants can use user-delegated OAuth at ordinary REST operations marked x-hitkeep-oauth-scope in OpenAPI while AI is enabled. Request only the operation's scope: sites:read or analytics:read for approved reads; goals:write for goals/funnels; annotations:write for timeline notes; sites:write for domain, retention and exclusions; opportunities:write for generation/status; billing:write for configured team Checkout. Each request intersects the grant with current user, team and site permissions. Billing-only consent selects a team without requiring sites; payment still needs human approval. No scopes grant credential issuance, impersonation, raw export or instance administration. Review and revoke grants in Settings → Connected applications.

MCP endpoint: https://cloud.hitkeep.eu/mcp. MCP accepts scoped bearer tokens for read-only aggregate analytics; OAuth requires sites:read and analytics:read plus explicitly consented sites.

A2A 1.0 synchronous analytics: https://cloud.hitkeep.eu/api/a2a/message:send. Use the API OAuth resource with sites:read and analytics:read. Discover tool inputs at https://cloud.hitkeep.eu/.well-known/agent-card.json.

API contract: https://cloud.hitkeep.eu/openapi.json. Skill installation and discovery grant no account or site access. No anonymous agent registration or Poppy session authentication is provided.
