Permissions Reference

Permission checks, effective permissions, ACL management, and ownership transfer.

Base path: /api/v1/permissions/

Permission values#

String values used in API bodies:

• READ
• WRITE
• DELETE
• CREATE
• SHARE
• MANAGE_PERMISSIONS

In effective-permission responses, also available as boolean flags: can_read, can_write, etc.

GET /api/v1/permissions/check#

Check a single permission.

Query:

Response: {allowed: true}.

POST /api/v1/permissions/check#

Same as GET with a JSON body.

Body: resource_type, resource_id, permission.

POST /api/v1/permissions/check/batch#

Batch check — up to 100 checks per request.

Body:

1
2
3
4
5
6

{
  "checks": [
    {"resource_type": "file", "resource_id": "fil_A", "permission": "WRITE"},
    {"resource_type": "file", "resource_id": "fil_B", "permission": "DELETE"}
  ]
}

Response:

1
2
3
4
5
6

{
  "results": [
    {"resource_type": "file", "resource_id": "fil_A", "permission": "WRITE", "allowed": true},
    {"resource_type": "file", "resource_id": "fil_B", "permission": "DELETE", "allowed": false}
  ]
}

GET /api/v1/permissions/effective#

Full set of effective permissions on a resource.

Query: resource_type, resource_id.

Response:

1
2
3
4
5
6
7
8

{
  "can_read": true,
  "can_write": true,
  "can_delete": false,
  "can_create": true,
  "can_share": false,
  "can_manage_permissions": false
}

ACL management#

GET /api/v1/permissions/acl/{resource_type}/{resource_id}#

Full ACL for a resource.

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

{
  "resource_type": "folder",
  "resource_id": "fld_01J3M",
  "inherit_from_parent": true,
  "entries": [
    {
      "id": "ace_01J3N",
      "principal_type": "group",
      "principal_id": "grp_01J3L",
      "principal_name": "Engineering",
      "principal_email": null,
      "permissions": ["READ", "WRITE", "CREATE", "DELETE"],
      "ace_type": "allow",
      "inherited": false,
      "inherit_to_children": true
    }
  ]
}

Required permission: MANAGE_PERMISSIONS.

POST /api/v1/permissions/acl/{resource_type}/{resource_id}#

Add an ACE. Returns 201.

Body:

Required permission: MANAGE_PERMISSIONS.

DELETE /api/v1/permissions/acl/{resource_type}/{resource_id}#

Remove an ACE. Returns 204.

Body: principal_type, principal_id, ace_type.

Required permission: MANAGE_PERMISSIONS.

PUT /api/v1/permissions/acl/{resource_type}/{resource_id}/inheritance#

Set inheritance mode.

Body:

Response: {resource_type, resource_id, inherit_from_parent}.

Required permission: MANAGE_PERMISSIONS.

Ownership#

POST /api/v1/permissions/ownership/{resource_type}/{resource_id}/transfer#

Transfer resource ownership.

Query: new_owner_id (user or group).

Response: {resource_type, resource_id, new_owner_id}.

Requires: Current owner, or tenant admin.

Error codes#

Related#

• Permissions and ACLs
• Shares Reference