Folders

Replace the users with access to a folder

PUT/folders/{id}/user-permissions
documents:writereplace_folder_user_permissionsDestructiveIdempotent

Makes the users you send the only users listed on the folder and returns every member. Up to 500 distinct members. Members left out are removed from the folder, its subfolders and documents; a changed level moves the user; new members are granted. Needs write access to the folder, else 403 forbidden. 422 on a bad body. dry_run previews it. Emits folder.updated with changed_fields user_permissions when the set changed, after commit; no email. Inherited members are listed and stay; they come from an ancestor. Sending the old members undoes it.

Path parameters

  • idstring (uuid)Required#

    The record's id.

Query parameters

  • dry_runboolean#

    Validate and run the call without committing it, returning what the real call would return with meta.dry_run set.

Headers

  • Idempotency-Keystring#

    Makes a retry safe. Send a new UUID for each new request and reuse it only to retry that request; the first response is replayed for 24 hours.

Request body

application/json, required · FolderUserPermissionReplace

  • membersFolderUserPermission[]Required#

    Every user that should have access, at most 500 with distinct ids. Anyone left out loses access.

{
  "members": [
    {
      "id": "9d8c7b6a-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "level": "write"
    }
  ]
}

Responses

200

Every user with access to the folder.

FolderUserPermission[]
{
  "data": [
    {
      "id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
      "level": "read"
    }
  ]
}
401

Authentication failed. error.code is one of invalid_token, expired, revoked.

Error
403

Authorization failed. error.code is forbidden when the token's user can't write the folder: any folder in the tree of a deal the token can see is writable, otherwise the folder's write list, write flags or super admin are needed. This is deliberately broader than the platform (no editor-role check) and stricter (the check applies where the platform skips it by role). Other codes are missing_scope, scope_disabled, org_disabled, ip_blocked, user_disabled.

Error
404

Resource not found (error.code = not_found).

Error
422

The request can't be processed (HTTP 422): validation_failed with one ErrorDetail per problem, or a code documented on the operation.

Error
429

Rate limit exceeded (error.code = rate_limited).

Error

Examples

curl -X PUT https://your-org-domain/kong/core/api/v2/folders/{id}/user-permissions\
  -H "Authorization: Bearer $HELM_API_KEY"\
  -H "Content-Type: application/json"\
  -d '{
  "members": [
    {
      "id": "9d8c7b6a-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "level": "write"
    }
  ]
}'