Who has access to whom?

Generally, few people are supposed to have access to user information. People with the Moderator and Administrator permissions always do. But there are a few cases where people with fewer permissions can gain access. Generally, the leader(s) of a specific team should have access to their team members. We’ll now say the members of their team fall into their jurisdiction. So for example, a ListAdministrator has access to users with the ListHelper and ListModerator permissions. However, this does not solve the problem of appoining new team members. They do not have an permissions yet and thus do not fall into the leaders’ jurisdiction. The most conversative option would be to require to have a Administrator appoint new team members. In the future it is planned to have people be able to request permissions from a team leader, which they can then grant or deny. That way, ListAdministrators will not have access to the entire user database, while still being able to completely manage their own team.

Note: Due to time constraints during implementation, the jurisdiction system is not implemented. The documentation describes how the endpoints would work if it was implemented. In reality, right now, all access to the user database needs to happen from an Administrator or Moderator account.

User listing

GET /users/

Allows the retrieval of a list of all pointercrate users (if you are pointercrate staff), or a list of all users that fall under your juristiction as a team leader.

Filtering

The result can be filtered by any of the following fields: id, name, has_permissions, display_name or name_contains (which only matches against the actual username, not the display name).

Pagination is done via the id field.

Request:

Response: 200 OK

Example request:

GET /api/v1/users/?name_contains=dust&has_permissions=1
Accept: application/json
Authorization: Bearer <omitted>

User retrieval

GET /users/ user_id /

Retrieves detailed information about the user with id user_id

Request:

Response: 200 OK

Response: 304 NOT MODIFIED

Returned if the If-None-Match header is set, and the etag for the user object matches one of the set values.

Errors:

Example request:

GET /api/v1/users/1/
Accept: application/json
Authorization: Bearer <omitted>

Modifying a user

PATCH /users/ user_id /

Modifies a given user. There are three types of users that can make requests to this endpoint

• People whose highest role is Administrator: Administrators can patch the display_name and permissions fields of everyone but themselves.
• People whose highest role is Moderator: Moderators can patch the display_name fields of everyone but themselves
• People whose highest role mark them as a team leader: These people can assign and remove roles that are related to their team and only if the user falls under their jurisdiction

Also note that you cannot grant (or revoke) other users Administrator permissions.

Request:

Response: 200 OK

Response: 304 NOT MODIFIED

Returned when the PATCH operation did not make any changes.

Errors:

Example request:

PATCH /api/v1/users/1/
Accept: application/json
Authorization: Bearer <omitted>
Content-Type: application/json
If-Match: 10434480491831244259

{
    "display_name": "testtest",
    "permissions": 3
}

Deleting a user

DELETE /users/ user_id /

Deletes a user account. This action is irreversible!

Request:

Response: 204 NO CONTENT

Nothing

Errors:

Example request:

DELETE /api/v1/users/1/
Accept: application/json
Authorization: Bearer <omitted>