Permissions

Permissions in Teamwork Graph API define who can view objects. The permissions system uses Access Control Lists (ACL) and user links to specify granular access controls for different actions, supporting third-party user scenarios.

Access Control Lists

When ingesting objects, the permissions attribute must be supplied to define who has access to view the object. Permissions are structured as an array of permission objects, each containing access controls.

The relation of each access control is AND. Within each access control, the relation of each principal is OR. For example, this list of ACLs defines ((user-123 OR group-456) AND (group-789)) can view the object.

1
2
permissions: [
  {
    accessControls: [
      {
        principals: [
          { type: 'USER', id: 'user-123' },
          { type: 'GROUP', id: 'group-456' }
        ]
      }
    ]
  },
  {
    accessControls: [
      {
        principals: [
          { type: 'GROUP', id: 'group-789' }
        ]
      }
    ]
  }
]

Principal types

Principal types are the kinds of users or groups that can be given permissions in an access control system. Teamwork Graph supports the following principle types:

User principal

An individual, identified by a user ID. The identifier should correlate to a user sent through the user operations.

1
2
{
  type: 'USER',
  id: 'user-external-id' // Required: External ID of the user
}

Group principal

A collection of users, identified by a group ID. The identifier should correlate to a group sent through the group operations.

1
2
{
  type: 'GROUP',
  id: 'group-external-id' // Required: External ID of the group
}

Atlassian workspace principal

Anyone who is part of the Atlassian workspace. That is, anyone belonging to the same cloudId where the object is ingested. This is useful if you do not have any permission model to replicate into Teamwork Graph, and want to allow anyone to view the object.

1
2
{
  type: 'ATLASSIAN_WORKSPACE'
  // No id required - grants access to anyone in the Atlassian workspace
}

Container principal

All users within an ACL of the container of the object. For example, for a document, this would be all users within an ACL for the document which contains it.

1
2
{
  type: 'CONTAINER'
  // No id required - grants access to all users within the container
}

User links

Access Control Lists replicate the third-party permission system. When we check that an Atlassian user has access to the Teamwork Graph object, we need to understand which third-party user the Atlassian user links to. Only when the user link is established will Teamwork Graph be able to enforce permissions against the Atlassian user querying data from the Teamwork Graph.

For permission checking, there are two ways we build this link:

1. Through the user mapping operation, which your app can directly invoke and tell us which third-party user links to which Atlassian account ID or email.

2. Through an OAuth2 authentication mechanism, defined using the auth object in your manifest. When the Atlassian user authenticates with the external system through 3LO, Teamwork Graph registers the link between the Atlassian user and the third-party user’s externalId. See the Teamwork Graph connector module.

Reference documentation

For more information on configuring permissions when ingesting data into Teamwork Graph via Forge, see the reference documentation: