Merge

An ACL (Access Control List) is a security feature used in systems (e.g., networking, file systems, databases) to define rules for what users or systems can access specific resources and what actions they can perform on them.

Key Components of an ACL in Merge's Ticketing API

The subject requesting access: <a href="https://docs.merge.dev/ticketing/users/" rel="nofollow noopener noreferrer" target="_blank">Users</a> or <a href="https://docs.merge.dev/ticketing/teams/" rel="nofollow noopener noreferrer" target="_blank">Teams</a> (a group of users)

The object to be accessed: <a href="https://docs.merge.dev/ticketing/tickets/" rel="nofollow noopener noreferrer" target="_blank">Tickets</a> and <a href="https://docs.merge.dev/ticketing/collections/" rel="nofollow noopener noreferrer" target="_blank">Collections</a> (a group of tickets)

The permissions cascade based on: <code>access_level</code> (enum field on tickets and collections to indicate where access is inherited from)

1. The subject requesting access: <a href="https://docs.merge.dev/ticketing/users/" rel="nofollow noopener noreferrer" target="_blank">Users</a> or <a href="https://docs.merge.dev/ticketing/teams/" rel="nofollow noopener noreferrer" target="_blank">Teams</a> (a group of users) 
2. The object to be accessed: <a href="https://docs.merge.dev/ticketing/tickets/" rel="nofollow noopener noreferrer" target="_blank">Tickets</a> and <a href="https://docs.merge.dev/ticketing/collections/" rel="nofollow noopener noreferrer" target="_blank">Collections</a> (a group of tickets)
3. The permissions cascade based on: <code>access_level</code> (enum field on tickets and collections to indicate where access is inherited from)

All of the following have access to read a Ticket

Assignees: Users or Teams that are directly responsible

Viewers: Inclusive of Users or Teams with any level of access. They could be directly assigned or tagged as a follower of a ticket/collection.

1. Assignees: Users or Teams that are directly responsible
2. Viewers: Inclusive of Users or Teams with any level of access. They could be directly assigned or tagged as a follower of a ticket/collection.

How to determine if an individual or a team has access to a specific ticket

Fetch all tickets of interest: <a href="https://docs.merge.dev/ticketing/tickets/" rel="nofollow noopener noreferrer" target="_blank">GET /tickets</a>

Determine users that have direct access to a Ticket

1. Use GET /ticket/{ticket_id}/viewers which returns a list of Viewer objects that point to a User id or Team id that are viewers of a Ticket with the given id.

Use a query param for <code>Teams</code> on the <code>Users</code> object (<a href="https://docs.merge.dev/ticketing/users/" rel="nofollow noopener noreferrer" target="_blank">GET /users?team={team_id}</a>) to return the list of Users that are associated with the teams with access to a ticket

Determine users that have indirect access to a Ticket by using the <code>access_level</code> field on the Ticket object

1. If <code>access_level</code> = <code>PRIVATE</code>, then everyone with access has direct access and can be retrieved via the GET /ticket/{ticket_id}/viewers endpoint. 
2. If <code>access_level</code> = <code>COLLECTION</code>, then all Viewers from the ticket's collections have indirect access. 
 1. Use GET /collections/{collection_id}/viewers to retrieve all users
 2. Use the <code>access_level</code> field on the Collection object to determine if you need to traverse a level higher to retrieve the parent collection and their viewers. 
3. If <code>access_level</code> = <code>COMPANY</code>, then all Users at the company have the ability to view the given ticket. 
4. If <code>access_level</code> = <code>PUBLIC</code>, then all Users and select external parties have access to the ticket.

1. Fetch all tickets of interest: <a href="https://docs.merge.dev/ticketing/tickets/" rel="nofollow noopener noreferrer" target="_blank">GET /tickets</a>
2. Determine users that have direct access to a Ticket
 1. Use GET /ticket/{ticket_id}/viewers which returns a list of Viewer objects that point to a User id or Team id that are viewers of a Ticket with the given id.
3. Use a query param for <code>Teams</code> on the <code>Users</code> object (<a href="https://docs.merge.dev/ticketing/users/" rel="nofollow noopener noreferrer" target="_blank">GET /users?team={team_id}</a>) to return the list of Users that are associated with the teams with access to a ticket
4. Determine users that have indirect access to a Ticket by using the <code>access_level</code> field on the Ticket object 
 1. If <code>access_level</code> = <code>PRIVATE</code>, then everyone with access has direct access and can be retrieved via the GET /ticket/{ticket_id}/viewers endpoint. 
 2. If <code>access_level</code> = <code>COLLECTION</code>, then all Viewers from the ticket's collections have indirect access. 
 1. Use GET /collections/{collection_id}/viewers to retrieve all users
 2. Use the <code>access_level</code> field on the Collection object to determine if you need to traverse a level higher to retrieve the parent collection and their viewers. 
 3. If <code>access_level</code> = <code>COMPANY</code>, then all Users at the company have the ability to view the given ticket. 
 4. If <code>access_level</code> = <code>PUBLIC</code>, then all Users and select external parties have access to the ticket.

How to determine which individuals or teams are assigned to a specific ticket

Users: see the <code>ticket.assignees</code> field

Teams: see the <code>ticket.assigned_teams</code> field

1. Fetch all tickets of interest: <a href="https://docs.merge.dev/ticketing/tickets/" rel="nofollow noopener noreferrer" target="_blank">GET /tickets</a>
2. Users: see the <code>ticket.assignees</code> field
3. Teams: see the <code>ticket.assigned_teams</code> field

Overrides: Ticket-level permissions override collection level permissions

Field level ACLs: Merge does not support permissions at the field level. Only a few systems like ServiceNow have support for field level permissions. If you would like to maintain access at the field level, consider having each individual authenticate using their credentials. That way permissions are maintained by the third-party platform.

- Overrides: Ticket-level permissions override collection level permissions
- Field level ACLs: Merge does not support permissions at the field level. Only a few systems like ServiceNow have support for field level permissions. If you would like to maintain access at the field level, consider having each individual authenticate using their credentials. That way permissions are maintained by the third-party platform.

Learn how to manage Ticketing ACLs with Merge's unified API

Ticketing Access Control List (ACLs)

Create a custom design with text, images, and links

ENUM Value for access_level on Tickets	Definitions
`PUBLIC`	All internal and select external users and teams can access this ticket
`COMPANY`	All users and teams from the company can access this ticket
`COLLECTION`	Only users and teams who have access to the parent collection can access this ticket
`PRIVATE`	Only a specific subset of users and teams can access this ticket

Ticketing Access Control List (ACLs)

Overview

How to determine ticket access

How to determine ticket assignment

Considerations