Heap Analytics User Management

Heap manages access through organizations and projects. Use this reference to onboard the collaborator quickly, adjust access safely, and document removals.

How Heap Structures Access

Heap uses a combined account and project permission model where organization-level roles intersect with project-level access grants. Understanding both layers is essential for secure collaborator management.

Organization Roles

Organization roles provide global capabilities across all projects and account settings.

Admin:

• Full organizational control including billing and user management
• Create, archive, and delete projects
• Configure SSO, SCIM, and security settings
• Access all projects regardless of project-level grants
• Manage API keys and integrations at organization level

Member:

• Standard user with no inherent organizational privileges
• Project access must be explicitly granted
• Cannot create projects or manage other users
• Cannot access billing or organizational settings
• Recommended default role for collaborators

Project Roles

Project roles determine what users can do within specific Heap environments (production, staging, development).

Admin:

• Full control over project settings and data
• Configure events, properties, and data definitions in Lexicon
• Manage project team members and their roles
• Set up integrations and data destinations (Activate)
• Configure Govern workflows and data quality rules
• Delete events or modify historical data labeling

Contributor:

• Create and edit analyses, dashboards, and segments
• Build user segments and cohorts
• Cannot modify Lexicon (event/property definitions)
• Cannot manage team members or integrations
• Cannot configure Govern or Activate features

Viewer:

• Read-only access to analyses and dashboards
• Can view existing charts and segments
• Cannot create new content or modify existing analyses
• Cannot access configuration settings
• Ideal for stakeholders who need visibility without analytical capabilities

Govern and Activate Add-Ons

Heap's Govern and Activate products add specialized permissions.

Govern (Data Quality):

• Data Manager: Define event taxonomies, approve/block events, manage data quality rules
• Reviewer: Review and comment on data quality issues, cannot approve/block
• Viewer: View tracking plans and data quality reports
• Govern permissions can be granted independently of project roles

Activate (Data Destinations):

• Admin: Configure destinations (warehouses, marketing platforms), set up syncs
• Contributor: Create audiences and segments for activation
• Viewer: View configured destinations and sync status
• Required when collaborators manage data pipelines or audience activation

Licensing consideration: Govern and Activate are separate add-ons. Document which collaborators need access to manage licensing costs.

Permissions Matrix

Account Types and Capabilities

Organization Administrators

Organization Admins manage global settings and have unrestricted access.

Use Org Admin for:

• IT leaders responsible for Heap platform governance
• Primary client contact managing the account
• Finance team handling billing (if separate from IT)

Grant to collaborators when:

• Collaborator is implementing Heap from scratch and needs to create projects
• Statement of work includes platform-level administration
• Collaborator manages multiple client projects requiring user administration
• Document admin access heavily in DPA

Avoid granting to collaborators when:

• Work is scoped to specific projects
• Collaborator doesn't need billing visibility
• User management can be handled by client team
• Default to Org Member with project-level access

Security considerations:

• Can access all projects and all data across the organization
• Can modify SSO/SCIM configuration affecting all users
• Can delete projects and historical data
• Limit to 2-3 trusted individuals maximum

Project Administrators

Project Admins have full control within assigned projects.

Use Project Admin for:

• Collaborators implementing tracking and configuring Lexicon
• Analytics leads managing data quality and definitions
• Implementation consultants setting up integrations
• Senior analysts responsible for data governance

Project Admin capabilities:

• Full access to project data and settings
• Configure events, properties, and sessions
• Manage project team (add/remove members, change roles)
• Set up Activate destinations and audience syncs
• Cannot delete the project without Org Admin role
• Cannot access other projects unless explicitly granted

Scoping best practice:

• Grant Admin on staging/development projects (freedom to experiment)
• Consider Contributor on production projects post-implementation
• Use separate accounts for configuration vs. analysis if possible

Project Contributors and Viewers

Standard roles for consuming analytics and building insights.

Contributor for:

• Collaborator analysts building dashboards and reports
• Data scientists creating segments and funnels
• Team members who need to analyze but not configure
• Most common role for ongoing analytics engagements

Viewer for:

• Client stakeholders consuming insights
• Compliance or audit teams needing read-only verification
• Collaborators during post-implementation monitoring
• Temporary access for demos or knowledge transfer

Auto-capture consideration: Heap automatically tracks all events. Contributors can see all auto-captured data unless specific properties are masked via Govern. Plan property-level restrictions for PII or sensitive data.

Service Accounts and API Access

Heap supports API access for programmatic data retrieval and configuration.

API Key types:

• Environment ID: Public identifier for sending events (Heap JavaScript SDK)
• API Key: Authentication for Data API (analytics queries)
• Admin API Key: For configuration and user management APIs (rare)

Service account pattern:

1. Create dedicated Heap user for API integrations (e.g., heap-api@client.com)
2. Grant Org Member role + specific project access (Viewer for read-only, Contributor for write)
3. Generate API key under that account
4. Store API key in secure vault
5. Document which integrations use the key

For collaborator integrations:

• Provide project-scoped API access only
• Use Viewer project role for read-only data extractions
• Use Contributor if collaborators need to create segments via API
• Rotate API keys annually or when engagement ends

Access Control and Data Governance

Project-Based Data Isolation

Heap isolates data at the project level. Use project structure to enforce data minimization.

Single project approach:

• All web and app data in one Heap project
• Simpler to manage, unified analytics
• Risk: Collaborators see all data if granted access
• Use Govern property masking to hide PII

Multi-project approach:

• Separate projects per brand, region, or sensitivity tier
• Grant collaborators access only to relevant projects
• Clearer compliance boundaries
• More complex: event definitions must be synced across projects

Environment segmentation:

• Create separate projects for production, staging, and development
• Grant broader access (Admin) to staging for testing
• Restrict to Contributor/Viewer on production to prevent accidental changes

Recommendation for collaborators: Grant access to minimum projects required. Use Govern to mask sensitive properties within granted projects.

Auto-Capture and Data Exposure

Heap automatically captures all page views, clicks, form submissions, and changes without manual instrumentation.

Data automatically captured:

• All DOM interactions (clicks, form fills, page views)
• URL parameters (may contain PII or sensitive data)
• Element attributes (class names, IDs, text content)
• Session and user identity (if identified via Heap.identify())

Governance implications:

• Contributors with project access can query all auto-captured data
• Sensitive data in URLs or form fields is captured by default
• User-level tracking possible if Heap.identify() is implemented

Mitigation strategies:

• Use Govern to mask PII properties (email, phone, address fields)
• Configure exclusion rules for sensitive URL parameters
• Review tracking plan with legal/privacy teams before granting collaborator access
• Document data exposure in Data Processing Agreements

Property-Level Hiding via Govern

Heap Govern allows hiding specific event properties from users.

Property masking:

• Hide PII fields (email, phone, credit card numbers)
• Restrict access to revenue or conversion values
• Block custom properties containing business-sensitive data

Implementation:

1. Navigate to Govern → Data → Properties
2. Select property to mask (e.g., "Email Address")
3. Configure visibility rules (hide from all users except admins)
4. Test with collaborator account to verify masking works

Limitations:

• Property hiding requires Govern add-on
• Masked properties still exist in raw data; just hidden from queries
• Cannot mask at user level (applies to all project members or none)

Team and Organization Structure

Single Organization Model

Most companies use one Heap organization for all projects.

Characteristics:

• Centralized billing and user management
• Easier to move users between projects
• Shared org-level settings (SSO, API quotas)

For collaborator management:

• Create collaborators as Org Members within primary organization
• Use project-level access to limit visibility
• Simpler onboarding (one set of credentials)

SSO and SAML Integration

Heap supports SAML-based single sign-on for enterprise accounts.

Supported identity providers:

• Okta
• Microsoft Azure AD / Entra ID
• OneLogin
• Google Workspace
• Any SAML 2.0 compliant provider

SSO benefits for collaborators:

• Centralized authentication through your IdP
• MFA enforced at IdP level
• Automatic deprovisioning when removed from IdP
• Aligns with corporate IAM policies

Implementation:

1. Configure Heap as SAML application in your IdP
2. Provide Heap support with IdP metadata
3. Map IdP attributes (email, name) to Heap user fields
4. Test with non-production users
5. Enable "Enforce SSO" to disable password logins

For collaborators:

• Collaborators authenticate via your SSO
• Add to IdP group granting Heap access
• Remove from group to auto-revoke Heap access
• Document IdP group mappings in access tracker

SCIM Provisioning

Heap supports SCIM 2.0 for automated user lifecycle management.

What SCIM automates:

• User creation when added to IdP groups
• User deactivation when removed from IdP groups
• Profile updates (name, email changes)
• Group-based project access assignments

Implementation:

1. Enable SCIM in Heap (Settings → Organization → SCIM)
2. Generate SCIM bearer token
3. Configure SCIM endpoint in your IdP
4. Map IdP groups to Heap organizations/projects
5. Test provisioning/deprovisioning workflow

Collaborator workflow:

• Create IdP group: "heap-client-analytics-team"
• Map to Heap project with Contributor role
• Add collaborator to IdP group → auto-provisioned in Heap
• Remove from group → auto-deprovisioned

Cautions:

• SCIM changes override manual Heap changes
• Always modify IdP groups, not Heap directly when SCIM is active
• Test deprovisioning to ensure collaborators are removed correctly

API Access and Authentication

Heap Data APIs

Heap provides several APIs for programmatic access.

Analytics API:

• Query Heap data programmatically (funnels, segmentation, retention)
• Read-only access to project data
• Requires API key tied to a user account

Admin API:

• Manage users, projects, and configuration programmatically
• Create/modify events and properties
• Requires Admin-level API key (rare for collaborators)

SQL API:

• Query Heap data using SQL syntax
• Access to raw event data and user properties
• Requires higher-tier Heap plan

Authentication:

• API keys tied to user accounts (inherit that user's permissions)
• Include API key in Authorization header: Authorization: Bearer YOUR_API_KEY
• No OAuth; API keys are long-lived credentials

API Key Management

Creating API keys:

1. Log in as the user who needs API access
2. Navigate to Account → API Keys
3. Generate new key
4. Copy key immediately (only shown once)
5. Store in secure vault

Key scoping:

• API keys inherit the user's organization role and project access
• User with Viewer role → API key has read-only access
• User with Admin role → API key can modify configurations

For collaborator integrations:

• Create API keys under collaborator service accounts
• Grant minimum project access required (Viewer for extractions)
• Name keys descriptively (e.g., "Collaborator ETL Integration")
• Rotate keys annually or when engagement ends

API Rate Limits

Heap enforces rate limits to protect platform performance.

Standard limits:

• Analytics API: 1,200 requests per hour per project
• SQL API: 100 queries per hour per project
• Admin API: 60 requests per hour per organization

For collaborator integrations:

• Implement exponential backoff on 429 errors
• Cache responses when appropriate
• Batch queries to reduce API calls
• Contact Heap support for higher limits if needed

Monitoring:

• Log API responses for rate limit headers
• Alert on repeated rate limit errors
• Review API usage monthly to optimize integrations

Audit Logging and Monitoring

Activity Logs

Heap tracks user actions and configuration changes.

Events logged:

• User logins and authentication
• Project access changes
• Lexicon modifications (event/property definitions)
• Integration configurations (Activate destinations)
• Data quality rule changes (Govern)
• User additions/removals

Accessing activity logs:

1. Navigate to Settings → Organization → Activity Log
2. Filter by user, action type, project, or date range
3. Export to CSV for archival

Retention:

• Heap retains activity logs for 1 year in the UI (varies by plan)
• Export quarterly for long-term compliance storage
• Include in SOC 2, ISO 27001, or GDPR documentation

What's NOT logged:

• Detailed user data access (who viewed which analyses)
• API calls (only key creation, not individual requests)
• Dashboard views or report exports

Collaborator Access Monitoring

Monitor for:

• Configuration changes in Lexicon (unexpected event modifications)
• New integrations or destinations added (Activate)
• User additions by collaborators (if they have Admin role)
• Govern rule changes affecting data quality
• Unusual export activity (large data downloads)

Approach:

• Review activity logs monthly
• Require collaborators to document changes in tickets
• Alert on changes outside business hours
• Check for dormant accounts (no logins in 60+ days)

Access Requests at a Glance

• Follow Add User Access to invite the service account and assign project rights.
• Use Update Access & Roles when the collaborator needs new project visibility or Governance/Activate permissions.
• Reference Remove User Access when the engagement ends or the account should be paused.

Add, Update, Remove at a Glance

• Add: Invite the collaborator, choose the account role, then assign project roles for each environment. Confirm whether Govern/Activate should be enabled.
• Update: Adjust roles as tracking plan ownership, messaging, or QA work changes. Update SSO groups if provisioning is automated.
• Remove: Remove project roles, drop the account role, and delete the user. Rotate any ingestion keys or API tokens they managed.

Platform Notes and Practical Steps

• Auto-capture can widen scope: Heap records many events out of the box. When adding users, check whether production projects contain properties that should stay hidden and whether Governance masking needs to be enabled for the collaborator.
• Lexicon editors need elevated roles: If the collaborator curates the tracking plan, ensure they have a role that can edit Lexicon entries; Viewers cannot adjust naming conventions or descriptions.
• Activate ties to tokens: Heap Activate destinations often rely on API tokens owned by a user. Before downgrading or removing, list which tokens belong to the collaborator and reissue them under a shared service account.
• Evidence to retain: Export Access Logs and capture a screenshot of the Members page showing project roles after every add/update/remove. File both artifacts with your IAM ticket for audits.

Roles to Maintain

• Organization Admins: Control billing, SSO, and project creation. Maintain at least two client admins and optionally the collaborator's admin when the collaborator handles configuration.
• Project Members: Analysts working inside a specific project. Scope the collaborator to only the projects tied to the engagement.
• Govern/Activate Admins: Optional roles when the collaborator helps manage data definitions or downstream audiences.

Best Practices for Team Access Management

Start with Least Privilege

Grant minimum organization and project roles required.

Decision framework:

1. Review SOW to identify deliverables
2. Map deliverables to Heap actions (configure events, build analyses, manage destinations)
3. Select narrowest role permitting those actions
4. Grant access only to required projects

Common mistakes:

• Granting Org Admin when Project Admin suffices
• Providing access to all projects when only one is in scope
• Enabling Govern/Activate when not contractually required

Use Staging Projects for Testing

Separate production and staging environments with different permission levels.

Pattern:

• Staging project: Project Admin for collaborators (freedom to experiment with Lexicon)
• Production project: Contributor or Viewer (limits configuration risk)
• Collaborators test in staging, client approves, then replicate to production

Time-Bound Access Reviews

Set calendar reminders to review collaborator access.

Review cadence:

• Monthly: Check for dormant accounts (no logins in 30+ days)
• Quarterly: Verify project access aligns with active contracts
• Annually: Audit organization roles and downgrade where possible

Mask PII Properties Proactively

If Heap auto-captures PII, mask it before granting collaborator access.

Implementation:

1. Identify PII properties (email, phone, address, user IDs)
2. Use Govern to mask from non-admin users
3. Test with collaborator account
4. Document masked properties in access tracker

Common Access Issues and Solutions

Issue: Collaborator Can't See Expected Project

Symptoms:

• User logs in but project doesn't appear
• "No projects available" message

Resolution steps:

1. Verify user accepted invitation email
2. Check that user is explicitly granted access to the project (Org Member role alone doesn't grant project access)
3. Confirm project isn't archived
4. If using SCIM, verify IdP group membership
5. Clear browser cache and retry

Prevention: After adding users, have them log in while you watch to confirm project visibility.

Issue: User Can't Edit Lexicon (Event Definitions)

Symptoms:

• Event/property edit buttons greyed out
• "You don't have permission" error

Resolution steps:

1. Verify user has Project Admin role (Contributors cannot edit Lexicon)
2. Check if Govern is enabled and user needs Data Manager permissions
3. Ensure user is accessing correct project (may have Contributor in one, Admin in another)

Prevention: Grant Project Admin or Govern Data Manager explicitly when collaborators need to edit tracking plans.

Issue: Govern Property Masking Not Working

Symptoms:

• Collaborator can still see masked properties
• Property appears in analysis despite masking configuration

Resolution steps:

1. Verify property masking was saved correctly in Govern
2. Have user log out and back in (permissions may be cached)
3. Check that user doesn't have Admin role bypassing masking
4. Confirm masking applies to correct property name (case-sensitive)

Prevention: Test property masking immediately after configuration with a test collaborator account.

Issue: API Calls Return 401 Unauthorized

Symptoms:

• API authentication fails
• "Invalid API key" errors

Resolution steps:

1. Verify API key is correct and hasn't been revoked
2. Check that API key is included in Authorization: Bearer header
3. Confirm the user account associated with the API key still has project access
4. Test with a different API endpoint to isolate issue

Prevention: Document which API keys belong to which integrations. Test keys immediately after generation.

Issue: Activate Destination Fails to Sync

Symptoms:

• Audience sync configured but not running
• Destination shows error status

Resolution steps:

1. Verify user has Activate Admin permissions
2. Check destination credentials are valid (API keys, OAuth tokens)
3. Confirm audience definition is valid and not empty
4. Review Activate logs for specific error messages
5. Test destination connectivity (Heap provides test sync button)

Prevention: Grant Activate Admin role explicitly. Test destinations immediately after configuration.

Security Recommendations

Enforce Multi-Factor Authentication

Heap supports MFA for enhanced security.

MFA configuration:

1. Navigate to Settings → Organization → Security
2. Enable "Require two-factor authentication"
3. Users must enroll in MFA on next login
4. Supports TOTP authenticator apps

For collaborators:

• Enforce MFA before granting production project access
• Verify during onboarding
• SSO users may satisfy MFA through IdP (no separate Heap MFA needed)

Use SSO for Collaborator Access

SSO provides stronger security and easier lifecycle management.

Benefits:

• Centralized authentication
• MFA enforced at IdP
• Automatic deprovisioning via SCIM
• Audit logs in both Heap and IdP

Migration:

• Enable SSO through Heap support
• Test with pilot collaborators
• Enable "Enforce SSO" to disable password logins

Rotate API Keys Regularly

API keys are long-lived and don't expire automatically.

Rotation schedule:

• Production integrations: Rotate annually
• High-privilege keys: Rotate every 6 months
• When collaborator team changes: Rotate immediately

Rotation process:

1. Generate new API key in Heap
2. Update collaborator integrations with new key
3. Test integrations
4. Delete old key
5. Document rotation in secrets management system

Monitor for Anomalous Configuration Changes

Set up alerts for unexpected activity.

Alert triggers:

• Lexicon changes (event/property modifications)
• New Activate destinations configured
• User role elevations
• Changes outside business hours
• Failed authentication attempts

Response workflow:

1. Detect anomaly through activity logs
2. Contact collaborator to verify legitimacy
3. If unauthorized: Revoke access immediately
4. Investigate scope of changes
5. Document incident and update procedures

Governance Checklist

Before granting access:

• Data Processing Agreement signed and filed
• Organization role selected (default to Member)
• Project access explicitly granted with appropriate roles
• Govern property masking configured for PII (if applicable)
• Govern/Activate permissions documented if granted
• SSO/SCIM group mappings configured (if applicable)
• MFA requirement verified
• API keys generated and stored securely (if needed)
• Access expiration date recorded

Quarterly review:

• Confirm project access aligns with active SOW
• Review activity logs for unexpected changes
• Check for dormant accounts (no logins in 60+ days)
• Verify API usage patterns remain normal
• Export and archive activity logs
• Confirm Govern property masking remains effective

When engagement ends:

• Remove from all projects
• Delete user or set to "No Access"
• Revoke all API keys
• Remove from SSO/SCIM groups
• Export final activity log
• Verify no Activate destinations remain under collaborator control
• Confirm collaborator deleted local exports per DPA
• Archive access documentation

Annual compliance:

• Review all Heap access against current contracts
• Audit organization roles for over-provisioning
• Test SCIM sync and SSO integration
• Review API key inventory and rotation schedule
• Update documentation for Heap feature changes

Related Documentation

• Add User Access - Step-by-step guide for inviting collaborators and assigning roles
• Update Access & Roles - How to modify permissions and project access
• Remove User Access - Offboarding process including API key revocation
• Heap Help Center - Official product documentation
• Heap API Documentation - Technical reference for integrations

Additional Resources

• Heap Platform: heap.io
• Heap API Docs: developers.heap.io
• Heap Status Page: status.heap.io
• Heap Security: heap.io/security

Track which Heap environments (production, staging) the collaborator can access and review quarterly. Export Heap's Access Logs after changes and attach them to your IAM records. Confirm SSO group mappings align with contractual scope before adding the collaborator. Document any shared app secrets or ingestion keys separately and rotate them on the agreed cadence.