---
title: Permissions Reference
path: reference/permissions
status: published
---

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:**

| Param | Notes |
|-------|-------|
| `resource_type` | `file`, `folder`, `share` |
| `resource_id` | |
| `permission` | One of the values above |

**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:**

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

**Response:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

| Field | Notes |
|-------|-------|
| `principal_type` | `user`, `group`, `everyone` |
| `principal_id` | Matching ID, or `"everyone"` |
| `permissions` | Array of permission names |
| `ace_type` | `allow` or `deny` |
| `inherit_to_children` | Default true |

**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:**

| Field | Notes |
|-------|-------|
| `inherit_from_parent` | `true` or `false` |
| `copy_inherited` | When disabling: copy inherited ACEs as direct entries first. Default false |

**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

| Code | HTTP | When |
|------|------|------|
| `AUTHZ_PERMISSION_DENIED` | 403 | Missing `MANAGE_PERMISSIONS` |
| `VALIDATION_ERROR` | 422 | Invalid permission name, principal type mismatch |
| `NOT_FOUND` | 404 | Resource or principal doesn't exist |

## Related

- [Permissions and ACLs](/docs/scaidrive/core-concepts/permissions-and-acls)
- [Shares Reference](/docs/scaidrive/reference/shares)