Skip to content
Help

Permissions API

The Permissions API provides an interface for modifying user and group permissions on a range of objects.

The Permissions API is a sub-API of data object details pages. Specifically:

  • Sources at /sources/{source-id}/permissions/
  • Layers at /layers/{layer-id}/permissions/
  • Tables at /tables/{table-id}/permissions/
  • Documents at /documents/{document-id}/permissions/
  • Sets at /sets/{set-id}/permissions/

The endpoints below are relative to these URLs, shown as …/permissions/.

Useful Definitions

Section titled “Useful Definitions”

Direct permission: A permission that is explicitly granted to a group or user for the object. Other permissions may be inherited via group membership or administrative rights. Only direct permissions can be edited via the permissions API.

Implicit permissions: Permissions inherited via ownership or group memberships. Implicit permissions are not editable via the permissions API. Also:

  • If the object is owned by a user, that user has full permissions on the object.
  • If the object is owned by a group, members of the group will have will have at least view (or equivalent) permissions on the object, and may have other permissions depending on their rights on the group.
  • Site administrators have full and irrevocable rights on the object.

Special groups: Groups that cannot own data and always exist in a Koordinates site. Some permissions are invalid for some or all special groups (for example, you cannot give ‘admin’ permissions to the everyone special group). They can be looked up by numeric ID but also using their natural key as below:

  • everyone : all users, including anonymous (not logged in) users
  • registered-users : includes all registered (logged in) users
  • members : refers to all members of the site
  • administrators : refers to all administrative users of the site

Identifiers for users and groups are in the form user.{user-id}, group.{group-id} or group.{group-key} (for special groups).

Important Notes

Section titled “Important Notes”

Permissions are linear, in that if an object allows find, view, download and admin permissions, a user with admin permission is also implicitly granted find, view and download.

While the API currently permits setting direct user permissions, this is currently not enabled via the web UI and might be subject to change. It is inadvisable to set direct user permissions at this time and only the Group permissions are documented below.

Direct permission list

Section titled “Direct permission list”
GET…/permissions/List direct permissions

Returns a list of direct permissions for this object.

Response 200

Headers

Content-Type: application/json

Body

[
    {
        "id": "group.everyone",
        "group": {
            "id": 1,
            "url": "https://{domain}/services/api/v1/groups/1/",
            "name": "Everyone"
        },
        "permission": "download"
    }
]
POST…/permissions/Create direct permission

Parameters

Section titled “Parameters”
  • group: string (required). Groups can be identified by id (e.g. 108), natural key (e.g. everyone) or API URL (e.g. https://{domain}/services/api/v1/groups/108/)
  • permission: string (required). The permission granted to the group. Example: admin.

Request

Headers

Content-Type: application/json

Body

{
    "group": "108",
    "permission": "admin"
}

Response 201

Body

{
    "id": "group.108",
    "group": {
        "id": 108,
        "url": "https://{domain}/services/api/v1/groups/108/",
        "name": "Example Group",
        "country": "NZ"
    },
    "permission": "admin"
}
PUT…/permissions/Replace direct permissions

Replaces all direct permissions for the layer or table.

Request

Headers

Content-Type: application/json

Body

[{
    "group": "registered-users",
    "permission": "view"
}]

Response 201

Headers

Content-Type: application/json

Body

[
    {
        "id": "group.registered-users",
        "group": {
            "id": 2,
            "url": "https://{domain}/services/api/v1/groups/2/",
            "name": "Registered users",
            "country": null
        },
        "permission": "view"
    }
]

Options requests for permission lists return additional information about valid permissions that can be applied to the object. These are in the form of an array of permission “choice” objects. For example:

"choices": [
    {
        "invalid_for_types": [],
        "display_name": "Can find",
        "description": null,
        "value": "find"
    },
    {
        "invalid_for_types": [],
        "display_name": "Can view",
        "description": null,
        "value": "view"
    },
    {
        "invalid_for_types": [],
        "display_name": "Can download",
        "description": null,
        "value": "download"
    },
    {
        "invalid_for_types": [
            "everyone",
            "registered-users"
        ],
        "display_name": "Can administer",
        "description": "Edit details and delete the file.",
        "value": "admin"
    }
]

In this example, there are four available permissions in increasing priority. The admin permission is not valid for the special groups everyone and registered-users.

Response 200

Headers

Content-Type: application/json

Body

{
    "name": "Direct Document Permissions List",
    "description": "",
    "renders": [
        "application/json",
        "text/html"
    ],
    "parses": [
        "application/json"
    ],
    "actions": {
        "PUT": {
            "id": {
                "type": "field",
                "required": false,
                "read_only": true
            },
            "group": {
                "type": "field",
                "required": false,
                "read_only": false
            },
            "user": {
                "type": "field",
                "required": false,
                "read_only": false
            },
            "permission": {
                "type": "choice",
                "required": true,
                "read_only": false,
                "choices": [
                    {
                        "invalid_for_types": [],
                        "display_name": "Can find",
                        "description": null,
                        "value": "find"
                    },
                    {
                        "invalid_for_types": [],
                        "display_name": "Can view",
                        "description": null,
                        "value": "view"
                    },
                    {
                        "invalid_for_types": [],
                        "display_name": "Can download",
                        "description": null,
                        "value": "download"
                    },
                    {
                        "invalid_for_types": [
                            "everyone",
                            "registered-users"
                        ],
                        "display_name": "Can administer",
                        "description": "Edit details and delete the file.",
                        "value": "admin"
                    }
                ]
            }
        },
        "POST": {
            "id": {
                "type": "field",
                "required": false,
                "read_only": true
            },
            "group": {
                "type": "field",
                "required": false,
                "read_only": false
            },
            "user": {
                "type": "field",
                "required": false,
                "read_only": false
            },
            "permission": {
                "type": "choice",
                "required": true,
                "read_only": false,
                "choices": [
                    {
                        "invalid_for_types": [],
                        "display_name": "Can find",
                        "description": null,
                        "value": "find"
                    },
                    {
                        "invalid_for_types": [],
                        "display_name": "Can view",
                        "description": null,
                        "value": "view"
                    },
                    {
                        "invalid_for_types": [],
                        "display_name": "Can download",
                        "description": null,
                        "value": "download"
                    },
                    {
                        "invalid_for_types": [
                            "everyone",
                            "registered-users"
                        ],
                        "display_name": "Can administer",
                        "description": "Edit details and delete the file.",
                        "value": "admin"
                    }
                ]
            }
        }
    }
}

Direct permissions for owner

Section titled “Direct permissions for owner”
GET…/permissions/{owner-key}/List direct permissions for owner

Response 200

Headers

Content-Type: application/json

Body

{
    "id": "group.everyone",
    "group": {
        "id": 1,
        "url": "https://{domain}/services/api/v1/groups/1/",
        "name": "Everyone"
    },
    "permission": "download"
}

Check permission for user

Section titled “Check permission for user”
GET…/permissions/user.{user-id}/{permission}/Check permission for user

Performs a check on the absolute permission for the user and permission. This takes into account direct and implicit permissions.

Use a user-id of anonymous to check permissions for users who are not logged in.

**Response 204

Response 404**