User management API

General remarks

This set of API endpoints are intended for privileged users only, since they expose private user information (email addresses, full names, etc.).

API endpoints

List all users

Request

GET /<api_version>/users/
Accept: application/json
Authorization: Token 1398dojk9sd8jf9hsd89hd

Successful response

Returns a list of all users on the platform.

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "username": "p_smith",
        "first_name": "Prudence,
        "last_name": "Smith",
        "email": "[email protected]",
        "organizations":
          [
            {
              "id": "0asjij9asjd8jh8ghashgd7",
              "name": "Habitat for Humanity"
            },
            {
              "id": "767fdfg987fvb09e8rdbdjg",
              "name": "Namati"
            }
        ],
        "last_login": "2016-03-15T12:34:56.000000Z",
        "is_active": true
    }
]

Filter

GET /users/?is_active=true

Returns all active users.

Search

Providing a query for parameter search will return a list of users where the user name, first or last name match the provided query (the matching is case-insensitive).

GET /users/?search=Smith

Order

Orders the response according to name.

GET /users/?ordering=name

For descending ordering add add a dash to the ordering attribute

GET /users/?ordering=-name

Errors

When the user is not authorised to view the user list

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "You are not allowed to list users."
}

Permissions

This action requires the user.view global permission.

Get a single user

Request

GET /users/<user-name>/
Accept: application/json
Authorization: Token 1398dojk9sd8jf9hsd89hd

Successful response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "username": "p_smith",
    "first_name": "Prudence,
    "last_name": "Smith",
    "email": "[email protected]",
    "organizations":
      [
        {
          "id": "0asjij9asjd8jh8ghashgd7",
          "name": "Habitat for Humanity"
        },
        {
          "id": "767fdfg987fvb09e8rdbdjg",
          "name": "Namati"
        }
    ],
    "last_login": "2016-03-15T12:34:56.000000Z",
    "is_active": true
}

Errors

When the user is not authorised to view user entries

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "You are not allowed to view users."
}

User not found

HTTP/1.1 404 Not found
Content-Type: application/json
{
  "error": "User does not exist"
}

The requesting user has sufficient permissions to view user entries, but the requested user entry does not exist.

Permissions

This action requires the user.view global permission.

Update a user

Request

The only fields that may be updated via this request are first_name, last_name, email and (the most common expected use case) is_active.

PATCH /users/<user-name>/
Content-Type: application/json
Authorization: Token 1398dojk9sd8jf9hsd89hd

{
    "is_active": false
}

Successful response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "username": "p_smith",
    "first_name": "Prudence,
    "last_name": "Smith",
    "email": "[email protected]",
    "organizations":
      [
        {
          "id": "0asjij9asjd8jh8ghashgd7",
          "name": "Habitat for Humanity"
        },
        {
          "id": "767fdfg987fvb09e8rdbdjg",
          "name": "Namati"
        }
    ],
    "last_login": "2016-03-15T12:34:56.000000Z",
    "is_active": false
}

Errors

When the request content contains invalid data

HTTP/1.1 400 Bad request
Content-Type: application/json

{
  "bad_field": "This field is not recognised."
}

When the request is not signed with a auth token

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "Please sign in."
}

When the user is not authorised to update user entries

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "You are not allowed to update user entries."
}

User not found

HTTP/1.1 404 Not found
Content-Type: application/json
{
  "error": "User does not exist"
}

Permissions

This action requires the user.update global permission.