Overview

Merge’s Zendesk integration syncs Tickets and key supporting objects (Brands, Roles, Groups, Organizations, Users, Contacts). Zendesk ticket visibility is primarily determined by an agent’s role configuration and their Brand access, with additional rules for Organizations, Groups, and Ticket Followers.

This guide explains the key permission behaviors you should plan for when building with Merge.

Scopes

Merge uses read scope to sync data from Zendesk.

Permission mapping (how Merge represents Zendesk access)

Object mapping

Merge maps Zendesk entities to Merge models like this:

• Ticket → Zendesk Ticket

  • Note: Ticket.organization_id tracks the requester’s organization, and can change if the requester’s organization changes.

• Collection → Zendesk Brand

  • Every Zendesk Ticket belongs to a Brand, and Brands act as a top-level container for ticket access logic.

• Role → Zendesk Role

  • View permissions are mapped based on Role.ticket_access.

• Team → Zendesk Organization and Group

  • Groups are groups of Zendesk agents.

  • Organizations are groups of agents and end users.

• Account → Zendesk Organization

• User → Zendesk Agent

• Contact → Zendesk End user

How Zendesk access works (high-level)

Zendesk ticket access is driven by:

• An agent’s Role.ticket_access (role-based ticket visibility rules), and

• Brand membership (agents generally must be in the same Brand as the Ticket to receive role-based access).

There are also important exceptions such as Ticket Followers, which do not follow the same role-based rules.

Merge’s permission behavior

Implementation details that affect your product:

Permission effects you will see

Merge currently supports Permission.effect for view access (future actions like create/edit/delete are planned).

Merge represents access using Permission objects that may have one of these behaviors:

• ALLOWED: direct access is granted to roles, teams, or users.

(Conceptually, you can think of “role-scoped” access as being expressed by a Permission that targets roles, sometimes further scoped by team membership and/or a brand collection.)

How Merge builds permissions

Merge builds Ticket view permissions in Zendesk based on:

• The Ticket’s Brand (mapped as a Collection), and

• The Role.ticket_access modes that exist in the Zendesk account, and

• The Ticket’s Organization, Group, Assignee, and Followers (when present).

A practical consequence is:

• Tickets may have multiple Permission objects attached (one per applicable access type), depending on which roles and fields exist for that linked account and that ticket.

Permissions by access type (Zendesk Role.ticket_access)

In all cases below, Brand matters: Zendesk requires every Ticket to be in a Brand, and role-based access is scoped to users who can access that Brand.

Admin access (Zendesk admin)

Zendesk admins have their own access behavior (not defined by Role.ticket_access). Merge represents this as:

• effect = ALLOWED

• applied_to_roles = [admin role(s)]

• applied_to_collections = [Ticket’s Brand Collection]

• actions = [VIEW]

Important nuance:

• A role with ticket_access = all is not necessarily an “admin,” because Brand access still matters.

• Zendesk admins must have access to all Brands and their roles cannot be customized.

ticket_access = all

If the linked account has roles with ticket_access = all, Merge grants view access as:

• effect = ALLOWED

• applied_to_roles = [roles where ticket_access = all]

• applied_to_collections = [Ticket’s Brand Collection]

• actions = [VIEW]

ticket_access = within-organization

If the Ticket has both a Brand and an Organization, and the linked account has roles with ticket_access = within-organization, Merge grants view access as:

• effect = ALLOWED

• applied_to_roles = [roles where ticket_access = within-organization]

• applied_to_teams = [Ticket’s Organization Team]

• applied_to_collections = [Ticket’s Brand Collection]

• actions = [VIEW]

ticket_access = within-groups

If the Ticket has both a Brand and a Group, and the linked account has roles with ticket_access = within-groups, Merge grants view access as:

• effect = ALLOWED

• applied_to_roles = [roles where ticket_access = within-groups]

• applied_to_teams = [Ticket’s Group Team]

• applied_to_collections = [Ticket’s Brand Collection]

• actions = [VIEW]

ticket_access = within-groups-and-public-groups

Merge represents this differently depending on whether the Ticket’s Group is private vs public (or missing):

If the Ticket’s Group is private

• effect = ALLOWED

• applied_to_roles = [roles where ticket_access = within-groups-and-public-groups]

• applied_to_teams = [Ticket’s Group Team]

• applied_to_collections = [Ticket’s Brand Collection]

• actions = [VIEW]

If the Ticket’s Group is public or the Ticket has no Group

• effect = ALLOWED

• applied_to_roles = [roles where ticket_access = within-groups-and-public-groups]

• applied_to_collections = [Ticket’s Brand Collection]

• actions = [VIEW]

ticket_access = assigned-only

If the Ticket has an Assignee and a Brand, and roles with ticket_access = assigned-only exist, Merge grants view access as:

• effect = ALLOWED

• applied_to_roles = [roles where ticket_access = assigned-only]

• applied_to_users = [Ticket’s assignee user]

• applied_to_collections = [Ticket’s Brand Collection]

• actions = [VIEW]

Ticket Followers (special case)

Ticket Followers do not follow Zendesk’s role-based ticket access rules. If a user is added as a follower, they can view the Ticket even if they are not in the same Brand and even if their role would not normally grant access.

Merge represents follower access as:

• effect = ALLOWED

• applied_to_users = [Ticket follower user(s)]

• actions = [VIEW]

Common scenarios to plan for

“Why can’t an agent with ‘all tickets’ access see a ticket?”

In Zendesk, “all” does not imply global admin access. Ticket visibility is still constrained by Brand membership requirements for role-based access.

“Why can someone see a ticket even though their role should not allow it?”

They may be a Ticket Follower. Followers can view tickets regardless of Brand membership and role-based ticket access rules.

“Why do some tickets have fewer permission grants than others?”

Merge only maps permission grants that are applicable:

• If a linked account has no roles for a given ticket_access type, that permission grant will not appear.

• If a ticket is missing required fields (for example, no assignee for assigned-only, or no group for within-groups), that permission grant will not appear.

“Why might organization-based access change over time?”

Zendesk ticket organization is tied to the requester’s organization, and it can change if the requester’s organization changes.