Multi-Admin, Roles & Permissions

PicPeak supports as many administrator accounts as you need, each with its own login. What an account can do is decided by the role assigned to it, and a role is a named set of permissions you control.

Roles that ship

Seven roles exist out of the box on the beta channel (six on stable, which has no Customer Support). All are marked as system roles, so none of them can be deleted, but all except Super Admin can be edited.

Super Admin is protected. It cannot be edited, and it automatically gains new permissions as features are added — the app re-grants anything missing on every start. That is deliberate: it guarantees at least one account can always reach everything, so an upgrade can never lock you out.

The preset roles (Solo Photographer, Team Photographer and Customer Support) are frozen at the set of permissions that existed when they were introduced. They do not pick up permissions from later releases. Treat them as starting points to clone rather than roles that keep pace on their own.

The role editor

Settings → Users (under People & access), then the Roles tab. It appears only for accounts that can manage roles. On the beta channel before v3.151.0-beta.0, and on stable, Users is a sidebar entry of its own.

From there you can create a role, clone an existing one and trim it, rename it, change its description, toggle individual permissions, and delete a role that no one is using. Each role shows how many permissions it holds and how many users have it.

The permission checkboxes are grouped by area — Events, Photos, Archives, Analytics, Email, Branding, CMS Pages, Settings & Config, Backup & Restore, Users & Roles, Activity Logs, Customers, Quotes, Invoices, Contracts, Accounting, Workflows, WhatsApp, System — with a select-all toggle per group.

A role’s key is fixed once created. The display name is not.

Guardrails

The editor stops you doing the things that would lock you out or let someone quietly promote themselves:

• Super Admin cannot be edited at all.
• You cannot edit your own role, unless you are a Super Admin.
• You can only grant permissions your own role already holds.
• Only a Super Admin can assign or invite another Super Admin.
• Only a Super Admin can change a Super Admin account at all: edit it, reset its password, deactivate, activate or delete it. users.edit and users.delete do not reach those accounts (beta channel from v3.135.3-beta.0).
• You cannot change your own role, demote the last Super Admin, or deactivate or delete the last Super Admin account.
• A role in use cannot be deleted until its users are reassigned.
• System roles cannot be deleted, and their names are reserved.

The dangerous-config split

settings.edit used to be one switch that opened every settings screen. It has been split so that a team member can manage everyday settings without being able to touch the things that move money, identity or access:

settings.edit keeps everything else.

Reading and writing are deliberately asymmetric. Viewing one of these screens needs either settings.view or the specific permission, so a role that could already see settings keeps seeing them. Changing anything needs the specific permission. In practice a role with plain settings.edit can open the security page and read it, but saving a change there fails.

The site URL is protected per field rather than per page: saving the General settings screen without altering the site URL works fine, and only an actual change to it requires settings.domains.

Events you do not own

Which galleries an account reaches is decided by three event permissions (beta channel from v3.155.0-beta.0; stable keeps the fixed rule described at the end of this section):

• Super Admin and roles with events.manage_all act on every gallery, including its share link.
• Roles with events.view_all only see every event in the list and on the event page. On an event the account cannot act on, the share link, client link, slideshow link and share token are withheld, and the Share link card says that only the gallery owner can see and share it.
• Every other role sees its own events, events without an owner, and galleries it is a team member of (see below). Another owner’s event answers “not found”. The archive list, the dashboard totals, upload status and the notification bell follow the same rule.
• Event-specific categories can only be created, renamed, given a cover photo or deleted by an account that can open that event. Global categories are unchanged.
• events.manage_all covers galleries only. Quotes, invoices, contracts, projects and transfers attached to another owner’s event stay with that owner.

On stable there are no such permissions: Super Admin and the built-in Admin role see every event (with links withheld for Admin on events it does not own), and every other role sees its own and ownerless events.

Gallery team

On the beta channel from v3.167.0-beta.0, the owner of a gallery can add other admin accounts as Team members in the gallery’s settings. A team member reaches that one gallery like its owner, within what their own role allows. The list of accounts to pick from shows other active admins; Super Admin accounts are only listed for a Super Admin.

Some things stay with the owner — the gallery’s creator, or for a gallery without an owner anyone who can open it, plus Super Admin and roles holding events.manage_all. A team member gets 403 for these (a change made through the gallery settings form answers with the code EVENT_OWNER_REQUIRED):

• deleting or archiving the gallery,
• the stored gallery password, the client PIN and password resets, and resending the gallery email,
• changing who is on the team and whether team uploads are reviewed,
• changing who receives the gallery email: the customer email, the admin email and the assigned customer accounts (from v3.175.1-beta.0). The settings form shows these read-only to a team member; saving the rest of the form with the stored values unchanged still works,
• CRM data on the gallery (quotes, invoices, contracts, projects) and transfers.

Review team uploads. With Review team members’ uploads before they are published on, photos uploaded by a team member whose role lacks photos.review (Review Team Uploads) stay hidden from guests and clients until the owner or a reviewer approves them on the Photos tab. Admin, Editor and Solo Photographer hold photos.review by default; Team Photographer does not. A held upload never replaces an existing photo, and a folder import by such a team member is refused with UPLOAD_REVIEW_REQUIRED.

Stable has no gallery team.

Reserved for Super Admin

A few actions could hand someone Super Admin power or a full copy of the instance, so no grantable permission unlocks them (builds containing PicPeak PR #1493 ):

• Changing the backup destination or database inclusion, and the destination connection test — see Backup and Restore.
• Restores and .picpeak imports.
• Mapping SSO logins to super_admin. Other SSO role targets must stay within the editor’s own permissions — see Admin SSO.

Other permission details

• Thumbnail settings and whole-library regeneration need settings.edit; regenerating one event needs photos.edit plus access to that event. The built-in Admin role holds settings.view but not settings.edit, so it can no longer change thumbnail settings. See Thumbnails. (PicPeak PR #1483 )
• Testing an IMAP connection, listing IMAP folders and testing a mail account need email.edit. See Email Notifications. (PicPeak PR #1485 )
• Webhook delivery details show the gallery share token and share URL only to roles with settings.integrations. See Webhooks. (PicPeak PR #1485 )

October 2026 changes

In builds containing PicPeak PR #1809 :

• Analytics tracker code. The tracker provider, the Umami and Rybbit URLs and the custom head HTML can only be changed by a Super Admin. They decide which script runs in visitors’ browsers, so settings.integrations no longer covers them; the other analytics fields are unchanged. Custom head HTML has since been removed entirely, and on the beta channel the Honour Do Not Track switch is Super Admin only as well. See Analytics.
• Settings with a screen of their own. The General, Security, Analytics and SEO save actions refuse keys that belong to another screen — backup_*, database_backup_*, rate_limit_*, max_image_requests_*, ledger_* and restore_* — with 400 and the code SETTINGS_OWNED_ELSEWHERE. Change them on the Backup, Security (rate limiting), Image Security, Accounting and Restore screens, which check their own permissions.
• Customers on events and projects. Assigning customer accounts to an event needs customers.events, on top of the event permission; without customers.view the event page shows no assigned customers. Linking a customer to a project needs customers.view, and a role without it does not see the project’s customer.
• Deal documents. The deal view lists quotes, contracts and invoices only for the document types the role may view (quotes.view, contracts.view, bills.view).
• Mailbox actions. Archive, Restore and Delete on the Messages page need email.edit; with email.view alone the page is read-only.
• S3 bucket list. Listing the buckets of the backup credentials is Super Admin only, like the destination test.
• Deleting administrators. A role with users.delete that is not Super Admin can only delete accounts whose role is within its own permissions, and not an account that still owns events or projects — reassign those first, or let a Super Admin delete it.
• Cancelling invitations. The same ceiling as for creating them: an invitation to Super Admin or to a role beyond your own permissions cannot be cancelled by you, and an accepted invitation cannot be cancelled at all.

Assigning a role

Settings → Users (on stable, Users in the sidebar) → edit a user → Role. Invitations pick a role at creation time.

Changes take effect on the next request the server handles, so there is no need to re-issue logins. The affected person may need to reload the page before menus and buttons reflect their new role, because the browser caches the permission list for the session.

What a blocked action looks like

The admin interface hides controls you lack permission for rather than showing them greyed out, so a narrower role sees a smaller app rather than a wall of disabled buttons. Settings tabs are filtered the same way, and land on the first tab the account is allowed to open.

If a request is made anyway — through the API, or a stale browser tab — the server answers 403 with {"error": "Insufficient permissions", "code": "FORBIDDEN"}.

Upgrading from the fixed roles

Existing installs keep working. Admin, Editor and Viewer keep exactly the permissions they had, and the five new settings permissions are granted to any role that already held settings.edit, which in practice means Super Admin only.

What you will notice after upgrading:

• Two new roles, Solo Photographer and Team Photographer, appear in the list.
• A Roles tab appears under Users.
• On the beta channel from v3.155.0-beta.0, the Customer Support role and the events.support, events.view_all and events.manage_all permissions appear. The built-in Admin role receives events.view_all, so it keeps seeing every event.
• Narrow roles may see fewer Settings tabs than before, because those tabs now have their own permissions.

New permissions from future features default to off for every role except Super Admin, so an upgrade never silently widens what your team can do.

Managing administrators

Settings → Users (on stable, Users in the sidebar). Create accounts directly or send an invitation, set each one’s role, deactivate accounts that should no longer have access, and see who did what in the activity log.

The Users area itself is behind the userManagement feature flag, which is on by default.

Staying signed in

The login page’s Remember me box extends the session from 24 hours to 30 days, and exempts it from the idle timeout that would otherwise sign a quiet admin out within the hour. The 30 days are absolute, and the session still ends immediately on logout, on a password change, when the token is revoked, or when the account is deactivated.

Guest activity in the bell

The notification bell in the admin header surfaces what guests are doing: a gallery being opened, photos being downloaded by a guest or by a customer account, and photos being favourited.

These are deliberately debounced so a busy gallery does not flood the bell — one open notification per gallery per six hours, one single-photo save per gallery per hour. Slideshow traffic is excluded entirely. There are no per-type settings for this yet.

In builds containing PicPeak PR #1809  the bell follows the same rule as the event list: Super Admin and Admin see every entry, every other role sees entries for its own events and for events without an owner. Entries that belong to no event (logins, settings changes) are shown to the roles that see everything.

Clear all never deletes anything: the entries are also the audit trail behind the activity log, contract history and customer timelines. In builds containing PicPeak PR #1813  it hides the entries from your bell only. Other administrators keep theirs, read/unread state is not touched, and a download summary that grows after you cleared it comes back. Mark all read still marks the entries read for everyone who can see them.

Related

• Admin SSO (OIDC) — sign in through an identity provider, with roles mapped from IdP claims.
• Customer Accounts — client-facing logins, which are entirely separate from admin accounts.