---
title: "HitKeep Roles and Site Permissions | HitKeep"
description: "Configure HitKeep RBAC for instance roles, site-scoped roles, team access, and analytics permissions without sharing dashboard credentials."
canonical: "https://hitkeep.com/guides/admin/permissions/"
---

# HitKeep Roles and Site Permissions

Access control over your analytics data should live on your infrastructure, not in a third-party identity cloud you don’t control. HitKeep’s role-based access control (RBAC) is enforced entirely on your instance, with granular roles at both the instance level and per site.

## Instance Roles

Instance roles apply across the entire HitKeep installation.

| Role | Permissions |
| --- | --- |
| owner | Full access: users, all sites, system settings, system status, maintenance actions, instance and site webhooks, and instance audit export |
| admin | Can view all sites, use system status, run maintenance actions, view instance audit logs, manage instance and site webhooks, and manage IP exclusion rules through the dedicated exclusion controls. Admins cannot perform owner-only settings actions, export instance audit logs, change retention, or use other broad site data mutation endpoints unless they also hold a site role that grants those actions. |
| user | Access only to explicitly assigned sites |

Change a user’s instance role (instance owner only) via:

- [Update an instance role](https://hitkeep.com/api/#tag/admin/POST/api/admin/users/%7Bid%7D/role)

Deleting a user is blocked if that user is the **last owner** of any team. Transfer team ownership first, then retry the instance-level delete. This prevents orphaned teams that no one can manage anymore.

## Administration Pages

The administration sidebar separates operational status from instance configuration:

- **System Status** shows runtime health, storage, ingestion volume, LRU cache status, backups, spam filter state, mail delivery status, maintenance actions, and instance audit logs.
- **System Settings** keeps the configuration workflows for users, sites, teams, and global filters.

These entries are shown in the sidebar only for users with the matching instance role. See [System Status and Settings](https://hitkeep.com/guides/admin/system-administration/) for the full operator reference.

## Site Roles

Site roles are scoped per user, per site. A user can be a `viewer` on one site and an `owner` on another.

| Role | What they can do |
| --- | --- |
| owner | Full site access: data, goals, funnels, webhooks, team, retention settings, stats reset, site deletion, and site-level IP exclusions |
| admin | Manage data controls, site-level IP exclusions, goals, funnels, webhooks, and team members |
| editor | Create and edit goals and funnels |
| viewer | Read-only access to dashboard and analytics |

Site-level IP exclusions are managed by site `owner` and `admin` roles through the normal site data-control permission. Instance `admin` users have a separate, narrow override for exclusion rules only, so they can remove operational noise without inheriting retention or ingestion mutation rights.

Resetting site stats and deleting a site require the site `owner` role, or an instance owner role. The stats reset flow is dashboard-session only. API client bearer tokens cannot use it.

Saved [Opportunity Recommendations](https://hitkeep.com/guides/analytics/opportunities/) follow the same split:

- users with `site.view` can read saved Opportunities for the site
- users with `site.manage_data` can generate or regenerate Opportunities, save them, dismiss them, or mark them done
- instance owners and admins configure the optional AI provider at the runtime level, not from a site page

## Site Permission REST API Reference

- [Add a site member](https://hitkeep.com/api/#tag/admin/POST/api/sites/%7Bid%7D/members)
- [Remove a site member](https://hitkeep.com/api/#tag/admin/DELETE/api/sites/%7Bid%7D/members/%7BuserId%7D)
- [Inspect the current user’s effective permissions](https://hitkeep.com/api/#tag/permissions/GET/api/user/permissions)

When you add site access for someone who is already in the site’s team, HitKeep grants or updates the site role directly. When the person is not in the team yet, HitKeep sends an invitation email and stages the requested site role. The role becomes effective after the recipient accepts the team invite.

Existing users sign in through the normal login flow before accepting the invite. When Google, GitHub, or Microsoft is configured, the invitation page can carry the one-time invitation through that provider flow and preserves the role requested by the invitation. New placeholder users can still set a password for the invited email address. No admin approval flow is required after acceptance.

## Service Accounts and API Access

For CI pipelines, integrations, or automated dashboards, use [API Clients](https://hitkeep.com/guides/security/api-clients/) instead of sharing user credentials. API client tokens are bearer tokens that can be revoked individually without affecting any other user or session.

API clients also govern MCP access and AI fetch ingest. MCP tokens need `site.view` for read-only aggregate analytics. AI fetch forwarders need `site.manage_data` for the site they write crawler records into.

Webhook configuration is intentionally excluded from API-client delegation. A human instance owner or administrator manages instance webhooks; a site owner or administrator manages that site’s webhooks. See [signed webhook permissions, verification, and delivery behavior](https://hitkeep.com/guides/integrations/webhooks/).

MCP clients can read saved Opportunities when their API client token can view the site. They cannot generate Opportunities or mutate status through MCP.

## Related

- [API Clients](https://hitkeep.com/guides/security/api-clients/)
- [Official MCP Server](https://hitkeep.com/guides/integrations/mcp/)
- [Signed Outbound Webhooks](https://hitkeep.com/guides/integrations/webhooks/)
- [AI Fetch Ingest](https://hitkeep.com/guides/tracking/ai-fetch-ingest/)
- [AI Fetch on AWS](https://hitkeep.com/guides/tracking/ai-fetch-aws/)
- [Opportunity Recommendations](https://hitkeep.com/guides/analytics/opportunities/)
- [Two-Factor Authentication](https://hitkeep.com/guides/security/two-factor-authentication/)
- [Social Sign-In](https://hitkeep.com/guides/security/social-sign-in/)
- [Shareable Dashboards](https://hitkeep.com/guides/sharing/dashboard-links/)
- [REST API Reference](https://hitkeep.com/api/)

HitKeep Cloud adds managed user provisioning with tenant-aware isolation and a hosted login flow, while keeping your analytics portable. [Start with HitKeep Cloud →](https://cloud.hitkeep.eu/signup?plan=free&billing=monthly&utm_source=hitkeep_docs&utm_medium=referral&utm_campaign=cloud_signup&utm_content=docs_inline)

[Previous Teams and data isolation](https://hitkeep.com/guides/admin/teams/)[Next System status and settings](https://hitkeep.com/guides/admin/system-administration/)