Manage Access

For V2 APIs, access is managed through the permissionsLocal object on the resource.

The permissionsLocal object displays the permissions that have been explicitly assigned to the resource. The resource may have additional permissions inherited from its parents through the permissionsInherited field. See ACL for more information.

In V2 APIs, permissions are represented as an array of actor-role pairs, and the inheritance of permissions can be controlled with the inherits boolean field. When inherits is set to false on a resource, the permissions are not inherited from the parent resources.

There are two approaches to manage permissions:

1. Complete replacement - Using the permissionsLocal field to completely replace existing permissions
2. Incremental updates - Using the updateAcl field with add and remove operations to modify specific permissions

Note: You must use either permissionsLocal or updateAcl in a single request, not both. Using both fields in the same request will result in a bad request error.

Below are the steps to add or remove permissions for a space.

Prerequisites

• A space should be created. To know more about creating a space refer here

Add permission for a space

Using PATCH API, space permissions can be updated in two ways:

Method 1: Complete replacement using permissionsLocal

This approach replaces all existing permissions with a new set. All previously assigned permissions not included in this request will be removed.

PATCH {baseUrl}/spaces/{spaceId}

• HEADER:

  • Authorization: Bearer {tid token}

• BODY:

Replace all permissions:

{
    "permissionsLocal": [
        {
            "actor": "trn:tid:application:{existingAppId}",
            "role": "spaceManager"
        },
        {
            "actor": "trn:tid:application:{newAppId}",
            "role": "spaceManager"
        }
    ]
}

Method 2: Incremental update using updateAcl

This approach adds specific permissions without affecting existing ones.

PATCH {baseUrl}/spaces/{spaceId}

• HEADER:

  • Authorization: Bearer {tid token}

• BODY:

Add specific permissions:

{
    "updateAcl": {
        "add": [
            {
                "actor": "trn:tid:application:{newAppId}",
                "role": "spaceManager"
            }
        ]
    }
}

Remove permission for a space

Using PATCH API, space permissions can be updated in two ways:

Method 1: Complete replacement using permissionsLocal

This approach replaces all existing permissions, effectively removing any that aren’t included in the new list.

PATCH {baseUrl}/spaces/{spaceId}

• HEADER:

  • Authorization: Bearer {tid token}

• BODY:

Replace permissions (removing some):

{
    "permissionsLocal": [
        {
            "actor": "trn:tid:application:{remainingAppId}",
            "role": "spaceManager"
        }
        // Any permissions not included here will be removed
    ]
}

Method 2: Incremental update using updateAcl

This approach removes specific permissions without affecting others.

PATCH {baseUrl}/spaces/{spaceId}

• HEADER:

  • Authorization: Bearer {tid token}

• BODY:

Remove specific permissions:

{
    "updateAcl": {
        "remove": [
            {
                "actor": "trn:tid:application:{appIdToRemove}",
                "role": "spaceManager"
            }
        ]
    }
}

Control permission inheritance

The V2 API allows you to control whether a resource inherits permissions from its parent using the inherits field:

PATCH {baseUrl}/spaces/{spaceId}/folders/{folderId}

• HEADER:

  • Authorization: Bearer {tid token}

• BODY:

Disable permission inheritance:

{
    "inherits": false,
    "permissionsLocal": [
        {
            "actor": "trn:tid:application:{appId}",
            "role": "contentContributor"
        }
    ]
}

When inherits is set to false, the resource will only use its explicitly assigned permissions and permissions set at the space level. Permissions from parent folders will not be inherited.

Similarly, folders and files permissions can also be updated. See here for updating permissions for folders and files. To know more about update permissions for space refer here.

Understanding V2 Permission Fields

When working with permissions in the V2 API, you’ll encounter several important fields in API responses:

• permissionsLocal: Permissions explicitly assigned to the specific resource
• permissionsInherited: Permissions inherited from parent resources through the hierarchy
• permissionsInheritedFoldersOnly: Permissions inherited from parent resources, excluding space and local permissions
• permissionsEvaluated: The effective combined permissions after applying inheritance rules
• capabilities: The specific actions the current user can perform on the resource

Example Permission Response

Permission fields

    {
    "permissionsLocal": {
        "contentViewer": [
        "trn:tid:user:f85bc802-5481-4581-b972-c4652d595ec7"
        ]
    },
    "permissionsInherited": {
        "contentManager": [
        "trn:tid:application:6529d0b3-5856-41ab-88b3-86f7955cddf1"
        ]
    },
    "permissionsInheritedFoldersOnly": {
        "contentManager": [
        "trn:tid:application:6529d0b3-5856-41ab-88b3-86f7955cddf1"
        ]
    },
    "permissionsEvaluated": {
        "contentManager": [
        "trn:tid:application:6529d0b3-5856-41ab-88b3-86f7955cddf1"
        ],
        "contentViewer": [
        "trn:tid:user:f85bc802-5481-4581-b972-c4652d595ec7"
        ]
    },
    "capabilities": [
        "Read",
        "Update",
        "Delete",
        "Restore",
        "ManageAccess"
    ]
    }

When querying resources, you can use the fields query parameter to request specific permission information or setcomplete query parameter as true:

    GET {baseUrl}/spaces/{spaceId}/folders/{folderId}?fields=permissionsInherited,permissionsEvaluated,capabilities