Update User Access in PostHog: Roles Guide

Overview

User access needs change over time. Engineers get promoted, product managers switch teams, contractors extend engagements, and stakeholders need deeper access. This guide covers how to update roles, modify project access, and adjust permissions without disrupting workflows.

Common Update Scenarios

Promote User to Admin

When: User needs to create projects, invite members, or manage organization settings

PostHog Cloud:

1. Go to Settings → Organization → Members
2. Find user in list
3. Click three dots menu → Edit
4. Change Organization role to Admin
5. Click Save

Self-hosted:

1. Navigate to Admin panel
2. Go to Staff users
3. Find user and click Edit
4. Check Staff status (for organization admin)
5. Save changes

Caution:

• Admin role grants significant permissions
• Can create/delete projects
• Can invite/remove users
• Use sparingly

Upgrade Project Role

When: User needs more permissions within a specific project (e.g., Viewer → Member, Member → Admin)

Steps:

1. Navigate to Settings → Project (select relevant project)
2. Go to Members tab
3. Find user in project members list
4. Click Edit or Change role
5. Select new role:
   • Viewer → Member: Can now create insights and dashboards
   • Member → Admin: Can now manage project settings
6. Click Save

Example: New engineer ready for production access

Before:
  - Production: Viewer

After:
  - Production: Member

Add User to Additional Projects

When: User's responsibilities expand to include other products or environments

Steps:

1. Go to Settings → Project (select new project)
2. Navigate to Members
3. Click Add member to project
4. Select user from dropdown
5. Choose appropriate role
6. Click Add member

Example: PM takes on second product

Before:
  - Web App: Member

After:
  - Web App: Member
  - Mobile App: Member

Remove User from Specific Project

When: User no longer needs access to a project but should remain in organization

Steps:

1. Navigate to Settings → Project (select project to remove from)
2. Go to Members
3. Find user in list
4. Click three dots menu → Remove from project
5. Confirm removal

User retains:

• Organization membership
• Access to other projects

Downgrade Permissions

When: User changes roles, moves to different team, or access was granted temporarily

Organization role downgrade:

1. Settings → Organization → Members
2. Find user
3. Edit → Change role to Member
4. Save

Project role downgrade:

1. Settings → Project → Members
2. Find user
3. Change role (e.g., Admin → Member, Member → Viewer)
4. Save

Example: Admin leaves project team

Before:
  - Production: Admin
  - Staging: Admin

After:
  - Production: Viewer
  - Staging: Viewer

Extending Contractor Access

When: Contractor engagement extended beyond original end date

Steps:

1. Update documentation:

   # PostHog Access Log
   
   ## contractor@agency.com
   - Original expiration: 2024-03-31
   - Extended to: 2024-06-30
   - Reason: Project extension
   - Approved by: Jane Doe
   

2. Verify access is still appropriate:

   • Same projects?
   • Same role?
   • Any changes needed?

3. Set new calendar reminder for new expiration date

4. Notify stakeholders of extended access

No PostHog changes needed if access level remains the same, but documentation and reminders are critical.

Adjusting SSO Mappings

When: Using SSO and need to change automatic role assignments

PostHog Cloud (Enterprise):

1. Contact PostHog support
2. Request SSO attribute mapping change
3. Provide:
   • Which attributes to map (e.g., department, role)
   • What PostHog roles they should map to
   • Test user accounts

Self-hosted:

1. Navigate to instance settings
2. Find SSO/SAML configuration
3. Modify attribute mappings
4. Test with a user account
5. Deploy changes

Example mapping:

IdP Attribute: department
  - Engineering → PostHog Admin
  - Product → PostHog Member
  - Executive → PostHog Viewer

IdP Attribute: contractor
  - true → Limited project access
  - false → Full access

Bulk Access Updates

When: Restructuring teams, changing project ownership, or onboarding multiple users

PostHog Cloud:

• Currently no bulk update UI
• Update users one at a time via Settings
• For large changes, contact PostHog support

Self-hosted with API:

// Example: Bulk update project access via API
const users = [
  { email: 'user1@example.com', role: 'member' },
  { email: 'user2@example.com', role: 'member' }
];

const projectId = 'your-project-id';
const apiKey = 'your-api-key';

for (const user of users) {
  await fetch(`https://app.posthog.com/api/projects/${projectId}/members/`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      user_email: user.email,
      level: user.role
    })
  });
}

Transferring Ownership of Resources

When: User leaves but created important dashboards, insights, or feature flags

Dashboards:

1. Navigate to dashboard
2. Click ... menu → Edit
3. Change Created by or Share with team
4. Consider pinning to prevent deletion

Insights:

• Insights are automatically shared within projects
• No transfer needed unless user has private insights
• Private insights deleted when user removed

Feature flags:

1. Navigate to Feature Flags
2. Find flags created by departing user
3. Document flag purpose and status
4. Reassign ownership (edit flag metadata)

Best practice: Use team accounts or service accounts for critical resources, not personal accounts.

Temporary Access Elevation

When: User needs temporary Admin access for a specific task (e.g., configuration change)

Process:

1. Document request:

   Date: 2024-03-15
   User: john@example.com
   Requested by: Manager
   Reason: Configure new feature flag experiment
   Duration: 24 hours
   Approved by: CTO
   

2. Grant elevated access:

   • Change role to Admin
   • Set calendar reminder to revert

3. Complete task

4. Revert access:

   • Return to Member role
   • Verify task completed
   • Document completion

Warning: Always revert temporary access. Forgotten elevated permissions are a security risk.

API Key Management

Rotating Personal API Keys

When: User's API key compromised or suspected breach

Steps:

1. User navigates to Settings → Profile
2. Find Personal API Key
3. Click Regenerate
4. Confirm action
5. Update any scripts/tools using old key

Admin can't rotate user API keys - user must do it themselves.

Updating Project API Keys

When: Project API key exposed in code, logs, or public repository

Steps:

1. Navigate to Settings → Project → Project API Key
2. Click Generate new key
3. Copy new key
4. Update all places using old key:
   • Frontend SDK initialization
   • Mobile app configuration
   • CI/CD environment variables
5. Test that tracking still works
6. Old key stops working immediately

Critical: Update SDK configuration before rotating, or tracking will break.

Permission Review Workflow

Quarterly access review:

1. Export current access:

   Organization: Acme Corp
   Total members: 42
   
   Admins (5):
     - alice@example.com
     - bob@example.com
     - charlie@example.com
     - diana@example.com
     - evan@example.com
   
   Members (35): [list]
   Viewers (2): [list]
   

2. Review with managers:

   • Does each person still need access?
   • Are roles still appropriate?
   • Any projects they no longer work on?

3. Make updates:

   • Remove departed employees
   • Downgrade unused permissions
   • Upgrade where needed

4. Document review:

   # Q1 2024 Access Review
   Date: 2024-03-31
   Reviewed by: Jane Doe (CTO)
   Actions:
     - Removed 3 departed contractors
     - Downgraded 2 users from Admin to Member
     - Added 5 new engineers
   Next review: 2024-06-30
   

Troubleshooting

User can't access project after role change:

• Have user log out and back in
• Clear browser cache
• Verify change was saved
• Check that user is still in organization

Admin role not working:

• Organization admins can't manage billing (Owner only)
• Project admins can't invite to organization (Organization admin needed)
• Verify correct admin level granted

SSO user permissions keep resetting:

• Check SSO attribute mapping
• IdP may be overwriting PostHog settings
• Configure SSO to not overwrite certain fields
• Contact PostHog support for help

User says they can't see new project:

• Verify project access was granted
• Check that user accepted organization invitation
• User may need to refresh or log out/in
• Verify project is not archived

Best Practices

Do:

• Document all permission changes
• Set reminders for temporary access
• Review access quarterly
• Use least privilege principle
• Require approval for Admin roles
• Audit changes in sensitive projects

Don't:

• Grant Admin access by default
• Forget to revert temporary access
• Skip documentation
• Leave departed users with access
• Share API keys instead of proper accounts

Security Checklist

When updating access, verify:

• Change approved by manager
• New permissions are minimum necessary
• Access documented in registry
• User informed of new permissions
• Review date set (if temporary)
• API keys rotated (if needed)
• Audit log entry created

Related Resources

• Add User Access - Initial onboarding
• Remove User Access - Offboarding
• PostHog User Management Overview - General concepts

Need help? Check PostHog user management docs or contact PostHog support.