How do I add and manage users?

1. Permissions required to add team members

To invite or manage team members (your colleagues who log in to Piano), you must have the Manage Team Members permission.

To verify you have this permission:

1. Go to My Account → Team Manager.

2. Click the pencil/edit icon next to your name.

3. Open Custom permissions.

4. Look for the Manage Team Members checkbox.

   • If checked, you have permission to manage team members.

   • If unchecked, you lack this permission.

If you don't have permission: ask an Admin to grant you the Manage Team Members permission. Once granted, refresh your browser and you should be able to invite and manage team members.

2. Adding team members in Team Manager

This section covers adding team members only. End users (subscribers and visitors on your site) are not added through Team Manager — they create their own accounts or can be added via the Piano dashboard's User section.

2.1 Basic steps

1. In the top right corner, go to Account → Team Manager.

2. Click Add User or Invite User.

3. Enter the required information:

   • Email address (the exact email the team member should log in with).

   • First Name.

   • Last Name.

   • Any other required fields.

4. Assign roles and permissions as appropriate.

5. Click Send Invite or Add User.

6. An invitation email is sent to the team member (see Sandbox-Specific Behavior if you're using Sandbox).

3. "User already exists" errors when adding team members

When inviting a team member, you may see one of these errors:

• Could not add user as member

• invalid request, user already exists

• User already exists

3.1 Root cause

These errors usually mean the email address already exists in Piano's global team member directory for your environment.

3.2 Resolution steps

1. Search your team member list with these filters:

   • Use the exact email address (search is case-sensitive in some scenarios).

   • Check filters: Status, Role, Features, Site groups.

   • Scroll through all results (pagination may be needed).

2. If the team member exists but is Pending or Disabled: see Pending and disabled team member handling below to reactivate or resend the invite.

3. If the email address can't be reused for any reason: use an email alias as a workaround.

4. Email alias workarounds

Email aliases are useful when you encounter conflicts adding a team member, or when you need to test multiple end-user creation scenarios in a non-production environment.

4.1 How plus-suffix aliasing works

Most email providers support the plus-suffix pattern: username+tag@domain.com

Examples:

• sarah@company.com → sarah+stage@company.com

• john.doe@company.com → john.doe+test@company.com

• alex@company.com → alex+1@company.com (for multiple test accounts)

Email delivery: Most providers deliver mail sent to the alias to the original mailbox.

• sarah+stage@company.com messages go to Sarah's inbox.

• Email filters may create separate folders based on the alias tag.

4.2 Important restrictions

• The user must log in using the aliased email, not the original email address.

• Piano treats aliases as different login identities — you can't switch between aliases after creating the account.

• If you create sarah+stage@company.com, Sarah must log in with that exact address.

4.3 When to use email aliases

• Testing team member or end-user creation in non-production environments.

• Creating multiple test accounts for the same person.

• Avoiding conflicts when an email is already in use elsewhere in the platform.

5. Team member limits

Most Piano accounts have a limit of approximately 2,000 team members. This limit applies to back-office team members in Team Manager, not to end users (subscribers and visitors), who are not subject to this cap.

5.1 If you're at or near the limit

1. Review and disable unused team member accounts.

   • Search for team members who haven't logged in recently.

   • Mark inactive team members as Disabled instead of deleting them.

   • This frees up space while preserving history.

2. Delete duplicate or test accounts if they're no longer needed.

3. Request a limit increase from Piano Support if you need more team members. Provide your environment, current team member count, and your business need for additional seats.

6. Pending and disabled team member handling

Team member records can have different statuses. Understanding these helps you troubleshoot issues when adding new team members.

6.1 Pending team members

A Pending status means the team member has been invited but hasn't yet activated their account.

If a Pending team member needs to activate:

1. Ask them to check their email (including spam/junk) for the invitation.

2. If they can't find the email, they can use Forgot password on the login page:

   • Go to the Piano login page for their environment.

   • Click Forgot password?

   • Enter their email address.

   • Follow the reset link to set their password and activate.

3. Alternatively, you can Resend Invitation from Team Manager.

Sandbox-specific behavior: see Sandbox-specific behavior for the activation workflow when invitation emails aren't sent.

6.2 Disabled team members

A Disabled status means the team member account exists but is not active.

To reactivate a Disabled team member:

1. Search for the team member in Team Manager.

2. Open the team member record.

3. Check the Active or Enable checkbox.

4. Assign or confirm roles and permissions.

5. Save your changes.

Don't create a duplicate team member. If the record already exists (even in Disabled status), re-enable it rather than creating a new one.

6.3 Duplicate team member records

In some cases, duplicate team member records may exist (for example, multiple entries with the same email, one Disabled and one Pending).

To resolve duplicates:

1. Keep the correct or most recent record.

2. Delete the duplicate or outdated records.

3. Once duplicates are removed, you can re-invite or re-enable the team member as needed.

This prevents conflicts and confusion in Team Manager.

7. End-user search troubleshooting

This section covers searching for end users (subscribers and visitors on your site) in Piano Dashboard. If you're having trouble finding end users, work through these issues.

7.1 Search input requirements

The Piano end-user search respects minimum character limits:

If your search query is too short for the selected mode, the search may appear to do nothing or return no results.

7.2 Email case sensitivity

Some Piano backend systems are case-sensitive for email addresses. If your search results look unexpected:

• Retry the search using the email exactly as it was stored when the end-user account was created.

• For example, if the end user was created as User@Company.com, search for that exact capitalization.

7.3 Large dataset handling

Very large or unfiltered end-user searches can time out or hit platform limits:

• Soft limit: around 10,000 records per search.

• If you hit this limit or experience timeouts:

  • Narrow your query by adding filters (date range, status, resource, site group, and so on).

  • Avoid loading "all end users" without any filters.

  • Use the API alternatives (see API alternatives for end-user lookup) if UI search is too slow.

8. End-user mining and search features

Piano Dashboard includes a User Mining or User Search feature for advanced end-user discovery and reporting. These features apply to subscribers and visitors, not to team members.

8.1 If the search/submit button is unresponsive

1. Open Piano Dashboard in a private/incognito window.

2. Disable browser extensions and ad blockers.

3. Switch to Chrome or another supported browser.

4. If the feature works in incognito, clear your regular browser cache and cookies, then try again.

8.2 If results spin indefinitely or show "No users found"

1. Clear browser cache and cookies, then log out and back in.

2. Re-check your filters and search criteria:

   • Overly restrictive filters can return zero results.

   • Verify date ranges, status, and other filters are correct.

3. Update your browser to the latest version.

4. Log out and back in to refresh your session.

8.3 Troubleshooting Mined User Reports

If you're generating a Mined User Report for end users and encountering issues:

1. Check for pre-selected Custom Fields:

   • Open the report configuration.

   • Deselect unnecessary custom fields. Too many can slow performance or cause errors.

   • Verify filters are not conflicting.

2. Verify browser compatibility:

   • Use Chrome (recommended).

   • Update your browser.

   • Try a different device if possible.

3. Log out and back in to refresh your session.

9. Browser and DevTools troubleshooting

Many issues with both team member management and end-user search are caused by cached data, cookies, or browser extensions.

9.1 Browser-level steps

1. Open Dashboard in a private/incognito window. If it works there, the issue is browser cache or extensions.

2. Clear cache and cookies for the Piano Dashboard site.

3. Disable browser extensions, especially:

   • Ad blockers.

   • Privacy tools.

   • Password managers (these sometimes interfere with forms).

4. Try a different supported browser (Chrome recommended).

5. Log out and back in to refresh your session.

6. If the UI remains unresponsive:

   • Restart your browser.

   • Restart your computer.

   • Disable VPN if you're using one. VPN routing can interfere with network requests.

9.2 DevTools troubleshooting (advanced)

If basic browser troubleshooting doesn't work:

1. Right-click on the unresponsive area and select Inspect to open DevTools.

2. Go to the Console tab and note any error messages.

3. Go to the Network tab:

   • Reproduce the issue (click search, submit form, and so on).

   • Look for relevant requests (commonly POST /publisher/user/search).

   • Check the HTTP status code:

     • 200 = success.

     • 502, 503 = server error (temporary outage).

     • Timeouts = the request took too long. Try narrowing your search.

4. Review the response body for error messages or timeout indicators. JSON errors may explain what went wrong.

5. Share findings with Piano Support if the error persists.

10. API alternatives for end-user lookup

If Piano Dashboard is slow or unavailable, you can retrieve end-user information via API as a workaround. These endpoints apply to subscribers and visitors, not to team members.

10.1 End-user search via API

If Dashboard search is failing or timing out, use this API endpoint:

POST /publisher/user/get
Parameters: aid (application ID), email

10.2 End-user export via API

For large end-user datasets when UI export is timing out:

1. Use the export endpoint to generate a Users report:

POST /publisher/export/create/userExport

2. Once the report has been generated, go to Reports → Download Center.

Notes:

• These endpoints require proper authentication and permissions.

• API usage may require API tokens or credentials specific to your account.

• Contact Piano Support for API documentation and authentication details.

11. Sandbox-specific behavior

11.1 Invitation emails in Sandbox

In Sandbox environments, invitation emails to team members may not be sent automatically. This is by design, to prevent test invitations from going to real mailboxes.

For Sandbox team members to activate their accounts:

1. Go to https://sandbox.piano.io/ (or your Sandbox URL).

2. Click Forgot password?

3. Enter the team member's email address.

4. Click the reset link (even though they never had a password) to set an initial password.

5. Log in with the new password.

This workaround bypasses the missing invitation email and lets Sandbox team members activate independently.

11.2 Stage and Production differences

In Stage and Production environments, invitation emails are sent to team members automatically. Team members remain Pending until they complete activation by:

• Clicking the invitation link in their email, or

• Using the Forgot password flow if they can't find the invitation.

12. When to contact Piano Support

Escalate to Piano Support if:

• You don't know who your administrator is. Support can help identify the correct contact.

• You need a team member record investigated (requires Support's backend access).

• You're at or near the 2,000-team-member limit and need to understand whether disabled team members count toward the limit.

• Browser and DevTools troubleshooting doesn't resolve end-user search or mining issues.

• You need API access to end-user data as a Dashboard alternative.

12.1 Information to provide

When contacting Support, include:

• Your environment (Production, Staging, or Sandbox).

• Whether the issue affects team members or end users.

• The affected email address(es).

• Error messages or screenshots.

• Steps you've already tried.

• Whether this affects multiple users or just one.

Last updated: June 25, 2026