collection.setPermissions

This method sets the private access permissions configured for a flipbook.

Request method

collection.setPermissions uses GET.

Endpoint:

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

The permissions parameter is a JSON string. URL-encode it when sending the request.

Request parameters

Name	Type	Required	Description
action	string	Yes	Must be collection.setPermissions.
apiKey	string	Yes	Your Flipsnack API key.
signature	string	Yes	Request signature generated with your API secret.
collectionHash	string	Yes	The hash of the flipbook.
permissions	JSON string	Yes	JSON object with a permissions array. This replaces the existing access list.

Permissions payload

The permissions parameter must be a JSON object with this structure:

{
  "permissions": [
    {
      "type": "teammate",
      "group": "mygroup2",
      "notifyViaEmail": true
    }
  ]
}

To remove all private access rows, send an empty array:

{
  "permissions": []
}

All permission objects in a non-empty permissions array must use the same type. For example, multiple teammate entries are valid in one request, but combining teammate and otp entries in the same request returns a bad request error.

Permission object fields

Name	Type	Required	Description
type	string	Yes	Permission type. Possible values: teammate, otp, sso.
email	string	Conditional	Email address for otp or teammate access. Required for otp. Optional for teammate. Not supported for sso.
group	string	Optional	Group name. Available only for teammate and sso. group is a field, not a permission type.
notifyViaEmail	boolean	No	If true, sends notification emails for this permission entry during this collection.setPermissions call. If omitted, it is treated as false.

email and group cannot be used together in the same permission object.

Permission types

teammate

Grants access to accepted readers from the workspace.

Shape	Description
{ "type": "teammate" }	Grants access to all accepted readers from the workspace.
{ "type": "teammate", "email": "[e-mail]" }	Grants access to one accepted reader from the workspace.
{ "type": "teammate", "group": "mygroup2" }	Grants access to accepted readers from the specified workspace group.

If a teammate group name does not exist, that permission entry is skipped.

If a teammate email is not an accepted reader in the workspace, that permission entry is skipped.

otp

Grants access through one-time password email authentication.

Shape	Description
{ "type": "otp", "email": "[e-mail]" }	Grants OTP access to the specified email address.

email is required for otp.

sso

Grants access through SSO authentication.

Shape	Description
{ "type": "sso" }	Grants access to all SSO-authenticated viewers for the workspace/profile.
{ "type": "sso", "group": "mygroup1" }	Grants access to SSO-authenticated viewers from the specified group.

email is not supported on sso permissions. Use teammate for per-email workspace reader access.

If an SSO group name does not exist, that permission entry is skipped.

Notification behavior

notifyViaEmail can be used on any permission type:

{
  "type": "teammate",
  "notifyViaEmail": true
}

For { "type": "teammate", "notifyViaEmail": true }, all accepted readers from the workspace are notified.

For group or email entries, only the matching group members or email recipient are notified.

notifyViaEmail is evaluated for the current collection.setPermissions request. If you call collection.setPermissions again with notifyViaEmail: true, emails can be sent again.

If notifyViaEmail is omitted, it is treated as false.

notifyViaEmail is not returned by collection.getPermissions.

Payload examples

Each request must send permissions of the same type.

Teammate permissions

{
  "permissions": [
    {
      "type": "teammate",
      "group": "mygroup2",
      "notifyViaEmail": true
    },
    {
      "type": "teammate",
      "email": "[e-mail]",
      "notifyViaEmail": true
    },
    {
      "type": "teammate",
      "email": "[e-mail]",
      "notifyViaEmail": false
    }
  ]
}

OTP permissions

{
  "permissions": [
    {
      "type": "otp",
      "email": "[e-mail]",
      "notifyViaEmail": true
    },
    {
      "type": "otp",
      "email": "[e-mail]",
      "notifyViaEmail": false
    }
  ]
}

SSO permissions

{
  "permissions": [
    {
      "type": "sso",
      "group": "mygroup1",
      "notifyViaEmail": true
    }
  ]
}

Request examples

Set teammate permissions

PERMISSIONS='{
  "permissions": [
    {
      "type": "teammate",
      "group": "mygroup2",
      "notifyViaEmail": true
    },
    {
      "type": "teammate",
      "email": "[e-mail]",
      "notifyViaEmail": true
    },
    {
      "type": "teammate",
      "email": "[e-mail]",
      "notifyViaEmail": false
    }
  ]
}'

curl -X GET \
     -G \
     https://api.flipsnack.com/v1/ \
     -d action=collection.setPermissions \
     -d apiKey=<YOUR-API-KEY> \
     -d signature=<YOUR-REQUEST-SIGNATURE> \
     -d collectionHash=<COLLECTION-HASH> \
     --data-urlencode "permissions=${PERMISSIONS}"

Set SSO permissions

curl -X GET \
     -G \
     https://api.flipsnack.com/v1/ \
     -d action=collection.setPermissions \
     -d apiKey=<YOUR-API-KEY> \
     -d signature=<YOUR-REQUEST-SIGNATURE> \
     -d collectionHash=<COLLECTION-HASH> \
     --data-urlencode 'permissions={"permissions":[{"type":"sso","group":"mygroup1","notifyViaEmail":true}]}'

Give access to all accepted workspace readers and notify them

curl -X GET \
     -G \
     https://api.flipsnack.com/v1/ \
     -d action=collection.setPermissions \
     -d apiKey=<YOUR-API-KEY> \
     -d signature=<YOUR-REQUEST-SIGNATURE> \
     -d collectionHash=<COLLECTION-HASH> \
     --data-urlencode 'permissions={"permissions":[{"type":"teammate","notifyViaEmail":true}]}'

Remove all permissions

curl -X GET \
     -G \
     https://api.flipsnack.com/v1/ \
     -d action=collection.setPermissions \
     -d apiKey=<YOUR-API-KEY> \
     -d signature=<YOUR-REQUEST-SIGNATURE> \
     -d collectionHash=<COLLECTION-HASH> \
     --data-urlencode 'permissions={"permissions":[]}'

Response examples

The response returns the saved permissions after invalid/skipped entries are removed.

Teammate response

{
  "code": 20,
  "status": "OK",
  "data": {
    "permissions": [
      {
        "type": "teammate",
        "group": "mygroup2"
      },
      {
        "type": "teammate",
        "email": "[e-mail]"
      }
    ]
  }
}

SSO response

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

After removing all permissions:

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

Skipped entries

Some permission entries are skipped instead of returning an error:

Entry	Behavior
teammate with a non-existent group	Skipped.
teammate with an email that is not an accepted workspace reader	Skipped.
sso with a non-existent group	Skipped.

If all entries are skipped, the flipbook has no saved access rows and the response contains an empty permissions array.

Validation errors

Invalid payload or permission objects return code 40 (Bad Request) with details in data.errors:

{
  "code": 40,
  "status": "Bad Request",
  "data": {
    "errors": [
      "Permissions cannot combine multiple types"
    ]
  }
}

Examples:

Case	Behavior
permissions is missing or is not valid JSON	Code 30 (missing parameter) or code 40 with Invalid permissions payload.
permissions.permissions is not an array	Code 40 with Invalid permissions payload.
Unknown type value	Code 40 with Invalid permission type at index N (got '…').
Multiple permission type values in the same permissions array	Code 40 with Permissions cannot combine multiple types.
email and group are both set on the same permission	Code 40 with Permission at index N cannot have both email and group.
group is used with otp	Code 40 with Permission at index N cannot have group (type=otp; group allowed only on teammate/sso).
otp without email	Code 40 with Permission at index N requires an email.
sso with email	Code 40 with SSO permission cannot include an email - use teammate or user for per-email access.
Invalid email format	Code 40 with Invalid email at index N.
Duplicate permission entry	Code 40 with Duplicate permission at index N.
notifyViaEmail is not a boolean	Code 40 with Invalid permissions format..
OTP permissions not on plan	Code 40 with OTP permissions are not available on your plan.
SSO permissions not on plan	Code 40 with SSO permissions are not available on your plan.
SSO not enabled for workspace	Code 40 with SSO is not enabled for this workspace.

Error responses

All errors return JSON with at least code and status. Validation failures on this action also include data.errors (string array).

Request, auth, and access errors

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

Permissions-specific errors

Code	Status	When
48	Permissions are only available for published private flipbooks	The flipbook is not published, is not private, or has a password set.
38	Collection is in progress. Please try again later	The flipbook is still publishing; retry after collectionStatus is no longer processing.
40	Bad Request	Invalid permissions payload or validation/plan/SSO errors (see data.errors).
50	Operation failed	The permissions service returned an unexpected response.

Example — not eligible:

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

Example — validation error:

{
  "code": 40,
  "status": "Bad Request",
  "data": {
    "errors": [
      "OTP permissions are not available on your plan"
    ]
  }
}