Add a User to Heap Analytics

Use this checklist to invite the collaborator into Heap. Heap provides digital insights and analytics requiring specific organization and project-level permissions to ensure appropriate access for implementation, analysis, and governance tasks.

Understanding Heap's Permission Model

Heap uses a two-tier permission structure combining organization-level roles with project-level access:

Organization Roles

Define account-wide capabilities and administrative rights:

Organization Admin:

• Full control over organization settings, billing, and security
• Can manage all members, create projects, and configure SSO/SCIM
• Access to audit logs, data governance tools, and API management
• Can install and manage Heap integrations across all projects
• Appropriate when the collaborator will handle implementation architecture or governance

Organization Member:

• Standard access focused on analytics and insights
• Can view assigned projects based on project-level permissions
• Cannot manage organization settings, billing, or other users
• Cannot create new projects or modify organization integrations
• Ideal for reporting, analysis, and project-specific implementation work

Project-Level Roles

Control what users can do within specific Heap projects (environments):

Project Manager:

• Full administrative control within the assigned project
• Can modify tracking plans, manage data definitions, and configure events
• Creates and manages charts, dashboards, funnels, and user segments
• Can export data and access SQL Lab for custom queries
• Manages project-specific integrations and data destinations
• Suitable for implementation leads and analytics architects

Project Analyst:

• Can create and edit analysis (charts, funnels, retention analyses)
• Access to user sessions, event data, and behavioral insights
• Can build and save dashboards for team use
• Cannot modify tracking plans or data governance settings
• Cannot manage integrations or export raw data
• Appropriate for analysts focusing on insights and reporting

Project Viewer:

• Read-only access to existing dashboards and saved analyses
• Can view charts, funnels, and user session replays
• Cannot create new analyses or modify existing content
• Cannot access SQL Lab or export raw data
• Ideal for stakeholders who need visibility without editing capabilities

Heap also supports SCIM provisioning for automated user lifecycle management and SSO (SAML 2.0) for enterprise authentication.

Prerequisites

Before inviting the collaborator, gather the following information and verify your permissions:

Required Information

• Heap organization URL: Confirm the exact subdomain (e.g., yourcompany.heap.io) for the engagement.
• Projects to assign: List all Heap projects the collaborator should access:
  • Production web project
  • Production mobile app project (iOS/Android)
  • Staging/development environments
  • Historical or archived projects if access is needed
• Authentication method: Determine if login will use email/password, Google OAuth, or enterprise SSO.
• Service account email: Collect the dedicated service account address (e.g., analytics-team@agency.com).
• Engagement scope: Review the statement of work to determine appropriate roles:
  • Implementation support = Project Manager
  • Analytics and insights = Project Analyst
  • Reporting review Viewer
  • Governance or multi-project oversight = Organization Admin

Prerequisites Verification

• Confirm you have Organization Admin privileges in Heap. Check by navigating to Account → Manage and ensuring you see organization settings.
• If using SSO/SCIM, coordinate with your identity team to pre-provision the user in your IdP and assign them to the appropriate Heap groups.
• Review your organization's security policies for external collaborators:
  • Multi-factor authentication requirements
  • IP allowlisting or VPN access rules
  • Password complexity and rotation schedules
  • Session timeout configurations
• Verify Heap environment inventory (production vs. staging projects) to ensure correct project assignments.
• Check if the collaborator needs access to any Heap add-ons: SQL Lab, Session Replay, or specific integrations.

Invitation Workflow

Follow these detailed steps to invite the collaborator:

1. Access Member Management

• Log into Heap using your Organization Admin credentials.
• Click your profile icon or organization name in the top-right corner.
• Select Account → Manage from the navigation menu.
• Choose the Members tab from the left sidebar.
• Review existing members to ensure no duplicate accounts exist.

2. Initiate the Invitation

• Click Invite New Members or the + button (location varies by Heap version).
• A modal or form will appear prompting for user details.

3. Enter User Information

• Email address: Enter the collaborator's service account email.
  • Use dedicated service accounts (not personal addresses) for better accountability.
  • Verify the email spelling to avoid delivery issues.
  • For SSO environments, ensure the email domain matches your SSO configuration.

4. Assign Organization Role

Select the appropriate organization-level permission:

• Choose Organization Admin if the collaborator will:
  • Configure tracking plans across multiple projects
  • Manage data governance and privacy settings
  • Set up integrations, destinations, or webhooks
  • Provide architectural guidance or implementation leadership
• Choose Organization Member if the collaborator will:
  • Focus on specific project analytics
  • Perform reporting and analysis tasks
  • Support implementation within defined project scope
  • Not require organization-wide administrative access

5. Assign Project Access and Roles

For each project the collaborator should access:

• Check the box next to the project name (e.g., "Production Web," "Staging Mobile").
• Select the appropriate project role from the dropdown:
  • Manager: For implementation work, tracking plan management, or data definition tasks.
  • Analyst: For creating analyses, building dashboards, and exploring user behavior.
  • Viewer: For reviewing pre-built dashboards and reports only.
• Include staging/development projects if the collaborator will QA implementation changes before production.
• Consider creating a dedicated "Agency Access" project if you want to sandbox external user access.

6. Add Invitation Notes

• Use the Note or Message field (if available) to document:
  • Engagement or project name
  • Statement of work reference or ticket number
  • Expected access duration for temporary engagements
  • Business justification for the access grant
• This information appears in audit logs and helps with future access reviews.

7. Send the Invitation

• Review all selections (email, organization role, project assignments).
• Click Send Invitation or Invite to dispatch the email.
• Heap will immediately send an invitation email to the specified address from noreply@heap.io.

The invitation email contains:

• A link to accept the invitation and set up the account
• The organization name and inviting administrator
• Expiration information (typically invitations expire after 7 days)

After Inviting

Complete these post-invitation steps to ensure successful onboarding:

Monitor Invitation Status

• The invited user appears in Account → Manage → Members → Pending Invites until they accept.
• Check this section periodically to confirm acceptance within the expected timeframe.
• Most collaborators accept within 24-48 hours; follow up if pending after 72 hours.

Verify Account Activation

Once the collaborator accepts:

• The account moves from "Pending Invites" to the main Members list.
• Verify the user shows the correct organization role and project assignments.
• Check the "Last Active" timestamp after the collaborator logs in for the first time.
• Ask the collaborator to confirm they can see the expected projects in their project selector.

Share Access Requirements and Policies

Communicate organization-specific requirements:

Authentication Details:

• Provide the Heap organization URL: https://yourcompany.heap.io
• Explain the login method (email/password, Google OAuth, or SSO portal link).
• If MFA is required, provide setup instructions or links to your IT documentation.
• Share VPN or IP allowlisting requirements if remote access is restricted.

Security Policies:

• Password complexity rules and rotation schedules.
• Session timeout duration and auto-logout behavior.
• Acceptable use policies for data access and export.
• Data privacy guidelines (GDPR, CCPA, HIPAA compliance as applicable).

Orientation Materials:

• Links to key dashboards and their purposes.
• Overview of Heap projects (which is production, which is staging).
• Documentation on event naming conventions and data definitions.
• Contact information for Heap-related questions or support escalation.

Update Documentation and Tracking

Maintain proper records for compliance and audit purposes:

Access Management Tracker:

• Log the invitation with these details:
  • Date and time of invitation
  • Inviting administrator name
  • Collaborator email and organization
  • Organization role and project assignments
  • Business justification and approval reference
  • Expected access duration (if temporary)
• Set calendar reminders for:
  • 30-day check-in to verify the collaborator is actively using access
  • Quarterly access reviews
  • Removal date for time-limited engagements

Project Documentation:

• Update your engagement file with Heap access confirmation.
• Store the invitation confirmation email with project records.
• Add the Heap access details to your Statement of Work tracking.
• Note any special configurations or custom permissions granted.

Role-Specific Post-Invitation Tasks

For Organization Admins

If you granted Organization Admin privileges:

• Share documentation on organization-wide integrations (Segment, Salesforce, data warehouses).
• Provide context on existing data governance rules and privacy configurations.
• Explain the organization's approach to project creation and environment management.
• Grant access to the Heap Help Center and developer documentation if they'll work with the API.

For Project Managers

If assigned as Project Manager on any projects:

• Review existing tracking plans and event taxonomy with the collaborator.
• Share definitions for custom events, properties, and user attributes.
• Explain SQL Lab access policies if data export is part of the engagement.
• Document any project-specific integrations or data destinations configured.

For Analysts and Viewers

If assigned lower-privilege roles:

• Share bookmarks or direct links to frequently accessed dashboards.
• Provide training on creating saved analyses or using specific Heap features.
• Explain limitations (e.g., "you can view but not edit existing dashboards").
• Set expectations about data freshness and update schedules.

Troubleshooting

Invitation Email Not Delivered

If the collaborator doesn't receive the invitation within 30 minutes:

Email Verification:

• Verify the email address was entered correctly without typos or extra spaces.
• Check if the email domain is spelled correctly.
• Resend the invitation from Account → Manage → Members → Pending Invites → Resend.

Email Filtering:

• Ask the collaborator to check spam/junk folders for messages from @heap.io or noreply@heap.io.
• Have your IT team or the collaborator's IT team allowlist:
  • heap.io
  • *.heap.io
  • heapanalytics.com
• Check corporate email gateways for blocked messages.

SSO Considerations:

• For SSO-enabled organizations, confirm the user exists in your identity provider first.
• Verify the email domain is authorized for SSO in Heap settings.
• Check that SCIM provisioning (if enabled) hasn't blocked the invitation.

Invitation Expiration:

• Heap invitations typically expire after 7 days.
• If expired, delete the pending invitation and send a fresh one.

SSO Login Fails After Accepting Invitation

If the collaborator accepts but cannot log in via SSO:

• Confirm the user is added to the correct IdP group mapped to Heap access.
• Verify SAML attribute mappings (email, name, group membership) are configured correctly.
• Check that the user's email in the IdP exactly matches the invited email in Heap.
• Test the SSO connection using Heap's SSO test feature in Account → Security → SSO Settings.
• Review IdP logs for authentication errors or attribute mapping issues.
• Ensure the collaborator is using the correct SSO login URL (not the generic Heap login page).

User Can't See Expected Projects

If the collaborator logs in successfully but doesn't see assigned projects:

• Return to Account → Manage → Members, find the user, and click Edit.
• Verify project checkboxes are selected and roles are assigned for each intended project.
• Confirm the projects are active and not archived.
• Check if the projects are hidden due to data retention settings or test environment flags.
• Ask the collaborator to refresh their browser or clear cache.
• Verify the collaborator is logged into the correct Heap organization (check the subdomain URL).

Need Temporary or Time-Limited Access

For engagements with defined end dates:

Manual Approach:

• Document the access end date in your IAM tracker.
• Set a calendar reminder 1 week before the end date to notify stakeholders.
• Create a second reminder on the actual end date to remove access.
• Add a note in the Heap member profile with the expiration date.

Automated Approach (if using SCIM):

• Configure your IdP to automatically deprovision users based on group membership expiration.
• Use time-bound group memberships in your IdP (e.g., Azure AD dynamic groups with expiration).
• Set up alerts in your IAM system for approaching access expirations.

Best Practices:

• For very short-term needs (less than 2 weeks), consider screen sharing instead of creating an account.
• Communicate the temporary nature of access in the invitation note.
• Send a reminder email to the collaborator 2 weeks before access expires.

Invitation Accepted But User Shows Wrong Role

If the accepted invitation results in incorrect permissions:

• This sometimes occurs with cached SSO sessions or SCIM sync conflicts.
• Edit the user in Account → Manage → Members and manually correct the organization and project roles.
• If using SCIM, verify the IdP group mappings are correct and force a re-sync.
• Ask the collaborator to log out completely and log back in.
• Check Heap's audit log in Account → Audit Log for any role changes that occurred during provisioning.

Multiple Accounts or Duplicate Emails

If you discover multiple accounts for the same collaborator:

• Heap ties accounts to email addresses; duplicates usually indicate different email variants.
• Identify which account should be retained (usually the most recently active).
• Transfer any critical content (dashboards, saved analyses) from the old account to the new one.
• Remove the incorrect or duplicate account via Account → Manage → Members → Remove.
• Update your IAM tracker to reflect the consolidation.

Best Practices

Security and Compliance

• Always use dedicated service accounts instead of personal email addresses for collaborators.
• Grant minimum necessary permissions (least privilege principle).
• Review and approve all invitation requests through a formal ticketing system.
• Maintain separation between production and staging environments when assigning project access.
• Implement quarterly access reviews to catch unnecessary or forgotten accounts.

Operational Excellence

• Standardize on naming conventions for service accounts (e.g., analytics-[vendor]@company.com).
• Create Heap "user templates" documenting standard role combinations for different engagement types.
• Use SCIM provisioning for organizations with frequent user lifecycle changes.
• Keep detailed notes in invitation records for future audit reference.
• Automate access review reminders using calendar invites or ticketing system workflows.

Communication

• Send a welcome email to the collaborator after access is granted with:
  • Heap organization URL and login instructions
  • Links to key dashboards and documentation
  • Point of contact for questions or issues
  • Expected engagement timeline and access duration
• CC the engagement manager or project lead on access confirmation communications.
• Set clear expectations about response times for access-related questions.