> For the complete documentation index, see [llms.txt](https://developers.flipsnack.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.flipsnack.com/api-reference/collection.getpermissions.md).

# collection.getPermissions

## Request method

`collection.getPermissions` uses **GET**.

Endpoint:

```
https://api.flipsnack.com/v1/
```

## Request parameters

<table><thead><tr><th width="177.27734375">Name</th><th width="131.22265625">Type</th><th width="112.9296875">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>action</code></td><td>string</td><td>Yes</td><td>Must be <code>collection.getPermissions</code>.</td></tr><tr><td><code>apiKey</code></td><td>string</td><td>Yes</td><td>Your Flipsnack API key.</td></tr><tr><td><code>signature</code></td><td>string</td><td>Yes</td><td>Request signature generated with your API secret.</td></tr><tr><td><code>collectionHash</code></td><td>string</td><td>Yes</td><td>The hash of the flipbook.</td></tr></tbody></table>

## Permission object

The response contains a `permissions` array. Each item has one of these `type` values:

<table><thead><tr><th width="194.91015625">Type</th><th width="182.7890625">Fields</th><th>Description</th></tr></thead><tbody><tr><td><code>teammate</code></td><td>none</td><td>All accepted readers from the workspace have access.</td></tr><tr><td><code>teammate</code></td><td><code>email</code></td><td>One accepted reader from the workspace has access.</td></tr><tr><td><code>teammate</code></td><td><code>group</code></td><td>All readers from the specified workspace group have access.</td></tr><tr><td><code>otp</code></td><td><code>email</code></td><td>A viewer has access through one-time password email authentication.</td></tr><tr><td><code>sso</code></td><td>none</td><td>All SSO-authenticated viewers for the workspace/profile have access.</td></tr><tr><td><code>sso</code></td><td><code>group</code></td><td>SSO-authenticated viewers from the specified group have access.</td></tr></tbody></table>

`group` is a field containing the group name. It is not a permission `type`.

`notifyViaEmail` is not returned by `collection.getPermissions`. It is a request-only option for `collection.setPermissions`.

## Request example

```bash
curl -X GET \
     -G \
     https://api.flipsnack.com/v1/ \
     -d action=collection.getPermissions \
     -d apiKey=<YOUR-API-KEY> \
     -d signature=<YOUR-REQUEST-SIGNATURE> \
     -d collectionHash=<COLLECTION-HASH>
```

## Response examples

Recommended usage is to keep permissions of the same `type` in one access list.

### Teammate response

```json
{
  "code": 20,
  "status": "OK",
  "data": {
    "permissions": [
      {
        "type": "teammate",
        "group": "mygroup2"
      },
      {
        "type": "teammate",
        "email": "maya.reader@example.com"
      }
    ]
  }
}
```

### SSO response

```json
{
  "code": 20,
  "status": "OK",
  "data": {
    "permissions": [
      {
        "type": "sso",
        "group": "mygroup1"
      }
    ]
  }
}
```

### OTP response

```json
{
  "code": 20,
  "status": "OK",
  "data": {
    "permissions": [
      {
        "type": "otp",
        "email": "olivia.reader@example.com"
      },
      {
        "type": "otp",
        "email": "ethan.viewer@example.com"
      }
    ]
  }
}
```

If no private access permissions are configured:

```json
{
  "code": 20,
  "status": "OK",
  "data": {
    "permissions": []
  }
}
```

## Notes

* The method is available only for flipbooks eligible for private access permissions. Private flipbooks can be created or set using the [`collection.create`](/api-reference/api-method-collection.create.md) and [`collection.update`](/api-reference/api-method-collection.update.md) actions.
* The order of returned permissions follows the saved access rows.
* Unknown/deleted groups or readers that no longer resolve may be omitted from the response.

## Error responses

All errors return JSON with at least `code` and `status`. Some failures also include a `data` object.

### Request, auth, and access errors

<table><thead><tr><th width="135.296875">Code</th><th width="311.7421875">Status</th><th>When</th></tr></thead><tbody><tr><td><code>30</code></td><td>Missing mandatory parameter</td><td><code>apiKey</code>, <code>signature</code>, <code>action</code>, or <code>collectionHash</code> is missing.</td></tr><tr><td><code>31</code></td><td>Requests per second limit exceeded</td><td>API rate limit exceeded.</td></tr><tr><td><code>32</code></td><td>Requests per minute limit exceeded</td><td>API rate limit exceeded.</td></tr><tr><td><code>41</code></td><td>Invalid credentials</td><td>The API key is invalid.</td></tr><tr><td><code>44</code></td><td>Invalid signature</td><td>The request signature is invalid (Flipsnack/MCP keys).</td></tr><tr><td><code>46</code></td><td>Invalid collection hash</td><td>The collection hash does not exist.</td></tr><tr><td><code>43</code></td><td>Forbidden</td><td>The collection does not belong to the API key workspace, is deleted, or the tenant does not match.</td></tr><tr><td><code>40</code></td><td>Bad Request</td><td>The action was sent with the wrong HTTP method (must be GET).</td></tr></tbody></table>

### Permissions-specific errors

<table><thead><tr><th width="139.671875">Code</th><th width="304">Status</th><th>When</th></tr></thead><tbody><tr><td><code>48</code></td><td>Permissions are only available for published private flipbooks</td><td>The flipbook is not published, is not private, or has a password set.</td></tr><tr><td><code>40</code></td><td>Bad Request</td><td>The permissions service rejected the request (see <code>data.errors</code> when present).</td></tr><tr><td><code>50</code></td><td>Operation failed</td><td>The permissions service returned an unexpected response.</td></tr></tbody></table>

Example — not eligible:

```json
{
  "code": 48,
  "status": "Permissions are only available for published private flipbooks"
}
```