Users & Groups API

The Users & Groups APIs provide functionality for managing user access, group permissions and group configuration.

List users

This API is only available to Site Administrators.

GET/users/List Users

Returns a paginated list of users who have access to your site. Use page and page_size (maximum 200); the X-Resource-Range header gives the range and total.

Response 200

Headers

Content-Type: application/json

Body

[
    {
        "id": 1,
        "url": "https://{domain}/services/api/v1.x/users/1/",
        "first_name": "Test",
        "last_name": "User",
        "country": "NZ",
        "email": "test.user@example.com",
        "is_locked": false,
        "is_site_admin": false,
        "is_site_owner": false,
        "is_group_admin": false,
        "is_ai_seat": false,
        "is_mcp_seat": false,
        "seat_type": "none",
        "kxai_credit_cap": null,
        "geotag": "global/oceania/new-zealand",
        "date_joined": "2018-09-05T00:11:16.287212Z",
        "is_verified": true,
        "is_remote_auth": false,
        "is_mfa_enabled": false,
        "last_seen": "2026-10-15T22:23:17.313830Z"
    }
]

Filtering users

Users can be filtered by the following parameters:

seat_type: The type of seat for the named user. One of paid, ai, mcp or none
group: A group identifier that the users should belong to. Multiple group IDs can be supplied with multiple group parameters. The list contains users who belong to all the groups queried. Special group identifiers can also be used (e.g. administrators; refer to the Permissions API for more examples).
q: keyword or email address for search. This is a keyword match rather than an exact one, so an email address can return several users.

An unknown seat_type returns 400.

Examples

List all site administrators: /users/?group=administrators
Find all paid seat users in group 100: /users/?seat_type=paid&group=100
Searching for a user by email address: /users/?q=test.user@koordinates.com

User detail

GET/users/{id}/Get User Detail

Returns detail about a specific User.

Response 200

Headers

Content-Type: application/json

Body

{
    "id": 1,
    "url": "https://{domain}/services/api/v1.x/users/1/",
    "first_name": "Test",
    "last_name": "User",
    "country": "NZ",
    "email": "test.user@example.com",
    "is_locked": false,
    "is_site_admin": false,
    "is_site_owner": false,
    "is_group_admin": false,
    "is_ai_seat": false,
    "is_mcp_seat": false,
    "seat_type": "none",
    "kxai_credit_cap": null,
    "geotag": "global/oceania/new-zealand",
    "date_joined": "2018-09-05T00:11:16.287212Z",
    "is_verified": true,
    "is_remote_auth": false,
    "is_mfa_enabled": false,
    "last_seen": "2026-10-15T22:23:17.313830Z"
}

List user permissions

GET/users/{id}/access/List User Permissions

Read-only, paginated list of a user’s permissions. The permission can be a group permission such as view, admin or manage_data. These are standard permissions that one can interact with using the Permissions API.

Example: /users/3/access/

Response 200

Headers

Content-Type: application/json

Body

[
    {
        "permission": "admin",
        "on": {
            "id": 123,
            "url": "https://{domain}/services/api/v1.x/groups/123/",
            "name": "Important Group",
            "country": "NZ",
            "org": "https://{domain}/services/api/v1.x/orgs/abc123/",
            "type": "normal"
        },
        "type": "group",
        "url": "https://{domain}/services/api/v1.x/groups/123/permissions/user.3/"
    }
]

List groups

GET/groups/Get Group List

Returns a list of Groups. Use q to search by name. type is normal for ordinary groups.

Response 200

Headers

Content-Type: application/json

Body

[
    {
        "id": 1,
        "url": "https://{domain}/services/api/v1.x/groups/1/",
        "name": "Example Group",
        "country": "NZ",
        "org": "https://{domain}/services/api/v1.x/orgs/abc123/",
        "type": "normal",
        "access_requests_enabled": false
    }
]

Create a group

POST/groups/Create Group

Creates a new Group. Note that only Site Administrators can create a new Group for a site.

Parameters

url_slug: string The human readable URL slug for the new Group
permissions: string (required) The permissions URL for the new Group
name: string (required) The name for the new Group
data_owner: string The owner of the Group’s data (site or group)
country: string (required) The code for the relevant country for this Group
access_requests_enabled: boolean Whether members of the site can request access to this Group
catalog_feeds_enabled: boolean Whether the Group’s data appears in public data feeds

Request

Headers

Content-Type: application/json

Body

{
    "url_slug": "this-is-a-new-group",
    "permissions": null,
    "name": "New Group",
    "data_owner": "site",
    "country": "NZ",
    "access_requests_enabled": false,
    "catalog_feeds_enabled": false
}

Response 201

Headers

Content-Type: application/json

Body

{
    "id": 2,
    "url": "https://{domain}/services/api/v1.x/groups/2/",
    "url_html": "https://{domain}/group/this-is-a-new-group/",
    "url_slug": "this-is-a-new-group",
    "permissions": "https://{domain}/services/api/v1.x/groups/2/permissions/",
    "name": "New Group",
    "data_owner": "site",
    "country": "NZ",
    "access_requests_enabled": false,
    "catalog_feeds_enabled": false
}

Group detail

GET/groups/{id}/Get Group Detail

Gets detailed information about a group. As well as the fields below, the response includes org, type, stats (counts of the group’s users, layers, tables, sets, documents and sources), description, description_html and membership.

Response 200

Headers

Content-Type: application/json

Body

{
    "id": 1,
    "url": "https://{domain}/services/api/v1.x/groups/1/",
    "url_html": "https://{domain}/group/this-is-group-1/",
    "url_slug": "this-is-group-1",
    "permissions": "https://{domain}/services/api/v1.x/groups/1/permissions/",
    "name": "Example Group",
    "data_owner": "site",
    "country": "NZ",
    "access_requests_enabled": false,
    "catalog_feeds_enabled": false
}