# Auth.md: HitKeep authentication

Use a scoped API-client bearer token created by the account owner at https://cloud.hitkeep.com/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.com/.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.com/.well-known/oauth-protected-resource/api.

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.com/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.com/api/a2a/message:send. Use the API OAuth resource with sites:read and analytics:read. Discover tool inputs at https://cloud.hitkeep.com/.well-known/agent-card.json.

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