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.
Returns a list of users who have access to your site.
Response 200
Headers
Content-Type: application/json
Body
[ { "id": 1, "url": "https://{domain}/services/api/v1/users/1/", "first_name": "Test", "last_name": "User", "country": "NZ", "email": "test.user@example.com", "is_locked": false, "is_site_admin": false, "seat_type": "none" } ]
Filtering Users
Users can be filtered by the following parameters:
seat_type: The type of seat for the named user. Eitherpaidornonegroup: A group identifier that the User's should belong to. Multiple group IDs can be supplied with multiplegroupparameters. The list contains users who belong to all the groups queried. Special group identifiers can also be used (e.g.administratorsrefer to the Permissions API for more examples).q: keyword or email address for search.
Examples
- List all site administrators:
/users/?group=administrators - Find all paid seat usersin group 100:
/users/?seat_type=paid&group=100 - Searching for a user by email address:
/users/?q=test.user@koordinates.com
User Detail
Returns detail about a specific User.
Response 200
Headers
Content-Type: application/json
Body
{ "id": 1, "url": "https://{domain}/services/api/v1/users/1/", "first_name": "Test", "last_name": "User", "country": "NZ", "email": "test.user@example.com", "is_locked": false, "is_site_admin": false, "seat_type": "none" }
List User Permissions
Read-only list of a user's permissions. 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://test.koordinates.com/services/api/v1/groups/123/", "name": "Important Group", "country": "NZ" }, "type": "group", "url": "https://{domain}/services/api/v1/groups/123/permissions/user.3/" } ]
List Groups
Returns a list of Groups.
Response 200
Headers
Content-Type: application/json
Body
[ { "id": 1, "url": "https://{domain}/services/api/v1/groups/1/", "name": "Example Group", "country": "NZ" } ]
Create a Group
Creates a new Group. Note that only Site Administrators can create a new Group for a site.
Parameters
- url_slug:
stringThe 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:
stringThe owner of the Group's data (siteorgroup) - country:
string(required) The code for the relevant county for this Group access_requests_enabled:
booleanWhether members of the site can request access to this Groupcatalog_feeds_enabled:
booleanWhether 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/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/groups/2/permissions/", "name": "New Group", "data_owner": "site", "country": "NZ", "access_requests_enabled": false, "catalog_feeds_enabled": false }
Group Detail
Gets detailed information about a group.
Response 200
Headers
Content-Type: application/json
Body
{ "id": 1, "url": "https://{domain}/services/api/v1/groups/1/", "url_html": "https://{domain}/group/this-is-group-1/", "url_slug": "this-is-group-1", "permissions": "https://{domain}/services/api/v1/groups/1/permissions/", "name": "Example Group", "data_owner": "site", "country": "NZ", "access_requests_enabled": false, "catalog_feeds_enabled": false }