Site Admin APIs

Get Started Account and Support File Formats and Data Types Find and Export Data Import Data Manage Your Site Plugins Publish Data Query API and Web Services Site Admin APIs
API Admin Glossary API Client Library Cartography API Data Catalog API Data Object Identifiers API Data Sources API Documents API Export API Feedback API Introducing the Admin API Layers & tables API License API Metadata API Permissions API Publishing API Redaction API Sets API Set scopes for an API token Users & Groups API
Update Data Users and Groups Desktop App Frequently Asked Questions
  1. Home
  2. Site Admin APIs
  3. Permissions API

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

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.
  • Administrators of the Koordinates Warehouse or Koordinates Enterprise Platform 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 ‘edit’ 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 
  • staff : refers to verified staff members of the Warehouse owner
  • administrators : refers to all administrative users of the Warehouse

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 view, download and edit permissions, a user with edit permission is also implicitly granted 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 /
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 /
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/groups/108/)
  • permission: string (required). The permission granted to the group. Example: edit. 

Request

Headers

Content-Type: application/json

Body

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

Response 201

Body

{
    "id": "group.108", 
    "group": {
        "id": 108, 
        "url": "https://{domain}/services/api/v1/groups/108/", 
        "name": "Example Group", 
        "country": "NZ"
    }, 
    "permission": "edit"
}
PUT /
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 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": null, 
        "value": "admin"
    }
]

In this example, there are three 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 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": null, 
                        "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 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": null, 
                        "value": "admin"
                    }
                ]
            }
        }
    }
}

Direct permissions for owner

GET /{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

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