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

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 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

Which permissions are available depends on the object type. For example, sets accept find, view and admin but not download. Use an OPTIONS request on the list to see the choices for an object. Sites can also disable some special groups: on a site where public data is turned off, giving everyone any permission returns 400 with Making data accessible to everyone on this site is disabled.

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

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

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.x/groups/1/",
            "name": "Everyone"
        },
        "permission": "download",
        "enable_access_requests": false,
        "url": "https://{domain}/services/api/v1.x/layers/1/permissions/group.everyone/"
    }
]

Each entry also has enable_access_requests (true, false or null) and the url of that permission. An object with no direct permissions returns [].

POST…/permissions/Create direct permission

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.x/groups/108/)
permission: string (required). The permission granted to the group. Example: admin.

Request

Headers

Content-Type: application/json

Body

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

Posting a group that already has a permission on the object returns 409 with {"error": "A permission for this group already exists"}. An invalid permission or unknown group returns 400 with the problem field under errors.

Response 201

Headers

Content-Type: application/json
Location: https://{domain}/services/api/v1.x/layers/1/permissions/group.108/

Body

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

PUT…/permissions/Replace direct permissions

Replaces all direct permissions for the object.

Request

Headers

Content-Type: application/json

Body

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

Response 200

Headers

Content-Type: application/json

Body

[
    {
        "id": "group.registered-users",
        "group": {
            "id": 2,
            "url": "https://{domain}/services/api/v1.x/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

GET…/permissions/{owner-key}/List direct permissions for owner

{owner-key} is an identifier such as group.108 or group.everyone. PUT changes the permission and DELETE removes it (returns 204).

Response 200

Headers

Content-Type: application/json

Body

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

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

The user has the permission. No body.

Response 404

The user doesn’t have the permission, or the permission name isn’t valid for this object.

{"detail": "That user doesn't have that permission on that object."}