Documents

Update document permissions

PATCH/documents/{documentId}/permissions
documents:writeset_document_permissionsDeprecatedSunset 2027-06-30

Updates a document's access control and returns it. Only the keys sent apply: permissions, read_access, write_access (user grants). The arrays returned include the folder's access. Unreadable: 404; unwritable: 403 forbidden. dry_run saves and sends nothing. Emits document.updated once after commit when something changed; no email. Undo by sending the old lists. Deprecated: use /documents/{id}/user-permissions and /documents/{id}/team-permissions. Withdrawn on 2027-06-30. Responses carry Deprecation, Sunset and a successor Link.

Path parameters

  • documentIdstring (uuid)Required#

    The document's public uuid.

Query parameters

  • dry_runboolean#

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

Request body

application/json, required

  • permissionsobject#

    Structured user/group access object.

  • read_accessstring (uuid)[]#
  • write_accessstring (uuid)[]#
{
  "read_access": [
    "3f1c9d22-1a2b-4c3d-8e4f-5a6b7c8d9e0f"
  ],
  "write_access": [
    "3f1c9d22-1a2b-4c3d-8e4f-5a6b7c8d9e0f"
  ]
}

Responses

200

OK

DocumentPermissions
{
  "data": {
    "id": "5e6f7081-92a3-4b4c-9d6e-7f8091a2b3c4",
    "permissions": {
      "user": {
        "none": [],
        "read": [
          "3f1c9d22-1a2b-4c3d-8e4f-5a6b7c8d9e0f"
        ],
        "write": [
          "a1b2c3d4-5e6f-4708-9a1b-2c3d4e5f6071"
        ]
      },
      "group": {
        "none": [],
        "read": [
          "8293a4b5-c6d7-4e8f-9012-3a4b5c6d7e8f"
        ],
        "write": []
      }
    },
    "read_access": [
      "3f1c9d22-1a2b-4c3d-8e4f-5a6b7c8d9e0f"
    ],
    "write_access": [
      "a1b2c3d4-5e6f-4708-9a1b-2c3d4e5f6071"
    ]
  }
}
401

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

Error
403

Authorization failed. error.code is one of org_disabled, ip_blocked, missing_scope, scope_disabled, user_disabled.

Error
404

Resource not found (error.code = not_found).

Error
422

Request validation failed (HTTP 422). The body is either the Laravel validation envelope (message + field-keyed errors) or the API error envelope for domain rejections (e.g. form_type_not_supported, folder_locked, parent_not_found, folder_not_empty).

429

Rate limit exceeded (error.code = rate_limited).

Error

Examples

curl -X PATCH https://your-org-domain/kong/core/api/v2/documents/{documentId}/permissions\
  -H "Authorization: Bearer $HELM_API_KEY"\
  -H "Content-Type: application/json"\
  -d '{
  "read_access": [
    "3f1c9d22-1a2b-4c3d-8e4f-5a6b7c8d9e0f"
  ],
  "write_access": [
    "3f1c9d22-1a2b-4c3d-8e4f-5a6b7c8d9e0f"
  ]
}'