Ticketing Permissions Guide

Last updated: January 6, 2026

A comprehensive guide to understanding and working with Ticketing Permissions in the Merge API.

Overview

Permissions is sub-model on both Ticket and Collection Common Models that control who can perform specific actions on ticketing records.

Permission Structure

Each permission object contains three key components:

permission.effect

Describes whether the permission is granted or not. Enum values:

  • ALLOWED: Permission is explicitly granted

  • DENIED: Permission is explicitly denied

  • INHERITED: Permission is inherited from a parent resource

permission.action

Specifies what kind of action is being granted or denied. Enum values:

  • VIEW: Permission to view or read the resource

  • CREATE: Permission to create new instances of the resource

  • EDIT: Permission to modify or update the resource

  • DELETE: Permission to remove or delete the resource

permission.applied_to dimensions

Defines which Common Model the permission applies to:

  • Roles: Represent the set of actions & access that a user with this role is allowed to perform

  • Teams: Represent one or more Users within the company receiving the ticket.

  • Users: Represent a user with a login to the ticketing system

Example Permissions Object

{
	"id": "b9d8ce270-b2ma-5tbc-09f4-3f36f53fe",
	"effect": "ALLOWED", // DENIED, INHERITED
	"actions": ["view", "create", "edit", "delete"],
	"applied_to_teams": ["b76ce270-bb3a-4ebc-93f4-3f36f53fe9cb"],
	"applied_to_roles": ["73a01a8c-f442-49d0-8e11-f226036bd188"],
	"applied_to_collections": [],
	"applied_to_users": []
}

Understanding Permission Logic

Permissions use a combination of AND and OR logic operators:

AND Logic Across Dimensions

When multiple dimensions are populated (e.g., both teams and roles are specified), apply AND logic across these dimensions. A user must satisfy conditions in all populated dimensions.

OR Logic Within Dimensions

Within each populated dimension, apply OR logic. A user only needs to match one of the values within that dimension.

Example

If a permission has:

  • teams: [team-1, team-2]

  • roles: [role-a, role-b]

A user must be in (team-1 OR team-2) AND (role-a OR role-b) to satisfy the permission.

Finding Users with Permissions

To identify which users have specific permissions, use the GET /users endpoint with the new plural query parameters:

New Plural Query Parameters

  • teams : Pass in one or more team IDs

  • roles : Pass in one or more role IDs

  • collections : Pass in one or more collection IDs

These new parameters accept multiple IDs and apply the same AND/OR logic that reflects how applied_to dimensions work.

Note: The older singular query params (team, role, collection) are still supported but only accept one ID each.

Usage Example

To find all users matching a permission's applied_to dimensions:

GET /users?teams=team-1,team-2&roles=role-a,role-b

This query returns users who are in (team-1 OR team-2) AND (role-a OR role-b), matching the permission logic.

Best Practices

  • Always check the effect field to determine if a permission grants or denies access

  • Use the plural query parameters when querying for multiple teams, roles, or collections

  • Remember that AND logic applies across different dimension types, while OR logic applies within each dimension

  • Consider inherited permissions when evaluating effective access rights

Integration Nuances

This section highlights current Permission action support levels and key nuances for each integration's permissions. Please see each ticketing system's integration nuances article to learn more about.

Asana

Current Support: VIEW action only. CREATE, EDIT, and DELETE coming soon.

Known Limitations

Public Tickets Not Associated with Projects

We cannot fully capture access control lists (ACLs) for public tickets that aren't associated with any project. The Asana API does not expose whether a task is private or public, and Asana has no intention of exposing it in the future.

Subtasks

We cannot capture all subtasks that the signed-in user can view in the UI. The project tasks endpoints only return tasks that are part of a project, while the private tasks endpoint only returns tasks directly assigned to the logged-in user.

See Asana permissions nuances guide for more details about Asana's integration nuances.

Jira

Current Support: VIEW action only. CREATE, EDIT, and DELETE coming soon.

Permission Effects

Jira uses two types of effects within Permissions:

  • ALLOWED: Explicitly grants access to specific users, roles, or groups

  • INHERITED: Only used on Ticket permissions. This specifies that the ticket's access is identical to the parent collection's permissions, with no additional restrictions

Known Limitations

Team-Managed Projects with Added Security

The Jira API does not return information about which roles are allowed to view an issue that has added security within a team-managed project. For issues with added security inside team-managed projects, we do not map any Permission objects at the ticket level.

Work Item Security Scheme Changes

When a work item security scheme is modified, we do not automatically update permission mappings for existing tickets until their security level is explicitly changed.

Example: Tickets A, B, and C in Project 1 have security level "high". According to the work item security scheme assigned to Project 1, "high" is accessible to any logged-in user. If the security scheme is later changed to restrict "high" to only a specific user, we cannot capture that change without a full resync of every ticket.

Atlassian's audit log's API does not capture changes to work item security schemes and webhook events do not support work item security schemes

We are evaluating different solutions to capture this more frequently without requiring a full resync of every ticket.

Team-Managed Projects with Added Security

The Jira API does not return information about which roles are allowed to view an issue that has added security within a team-managed project. For issues with added security inside team-managed projects, we do not map any TicketingPermission objects at the ticket level.

Unmapped Holder Types

Some Jira holder types are currently not mapped to Merge:

  • Service Space Customer - Portal Access

  • Current assignee

  • Reporter

BROWSE_PROJECTS Permission Bug

The BROWSE_PROJECTS permission has a known bug for company-managed project permission schemes. If any one of the following holder types is assigned this permission, any user who is logged into the Jira site can see the name of the space on the View All Spaces page and when searching for work items. They cannot view the work items inside the space.

  • User custom field value

  • Group custom field value

  • Reporter

  • Current assignee

We map "Any Logged In User" at the project level if any of these four roles are assigned.

See Jira permissions nuances guide for more details about Jira's integration nuances.

Linear

Current Support: VIEW action only. CREATE, EDIT, and DELETE coming soon.

See Linear permissions nuances guide for more details about Linear's integration nuances.

Zendesk

Current Support: VIEW action only. CREATE, EDIT, and DELETE coming soon.

See Zendesk permissions nuances guide for more details about Zendesk's integration nuances.