Overview
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 object to be accessed: Tickets and Collections (a group of tickets)
The permissions allowed: Roles
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 e.g., assignees and followers, etc
How to determine ticket access
How to determine if an individual or a team has access to a specific ticket
Fetch all tickets of interest: GET /tickets
Determine users that have access to a Ticket
Use GET /ticket/{ticket_id}/viewers which returns a list of Permission 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
Teamson theUsersobject (GET /users?team={team_id}) to return the list of Users that are associated with the teams with access to a ticket
How to determine ticket assignment
How to determine which individuals or teams are assigned to a specific ticket
Fetch all tickets of interest GET /tickets
Users: see the ticket.assignees field
Teams: see the ticket.assigned_teams field
How to determine available user actions
How to determine what level of access a user has been granted for a specific ticket
The Roles Common Model is used to get all roles available in Merge
The Merge User.roles Common Model relates a User to their role(s)
The Merge Ticket.roles Common Model indicates the roles that have access to this ticket and what specific actions e.g., read, write
To related users to their ticketing roles, hit the Users endpoints and filter on users with those specific roles GET /users?role={role_id}
Considerations
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.