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/

Pagination:
This endpoint supports pagination and filtering via query parameters. Please see the documentation on pagination for information on the additional request and response fields headers.

Access Restrictions:
Access to this endpoint requires at least Moderator or be the leader of a team.

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.

Pagination is done via the id field.

Request:

Header Expected Value Optional
Authorization Pointercrate access token false

Response: 200 OK

Header Value
Content-Type application/json
Field Type Description
- List[User] A list of users

Example request:

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

User retrieval

GET /users/ user_id /

Access Restrictions:
Access to this endpoint requires at least Moderator or have the requested user fall inside your jurisdiction

Retrieves detailed information about the user with id user_id

Request:

Header Expected Value Optional
Authorization Pointercrate access token false
If-Match Conditional request header. If the etag value of the requested data matches any of the here provided values, the data is returned as requested. Otherwise a 412 PRECONDITION FAILED response is generated true
If-None-Match Conditional request header. If the etag value of the requested data does not match any of the here provided values, if it returned as requested. Otherwise, a 304 NOT MODIFED response is generated true

Response: 200 OK

Header Value
Content-Type application/json
ETag unsigned 64 bit hash of the user object
Field Type Description
data User The requested user object

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.

Header Value
ETag unsigned 64 bit hash of the user object

Errors:

Status code Error code Description
404 40401 No user with id user_id was found

Example request:

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

Modifying a user

PATCH /users/ user_id /

Access Restrictions:
Access to this endpoint requires at least Moderator or have the requested user fall inside your jurisdiction. Exactly which fields you can modify is explained below

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:

Header Expected Value Optional
Content-Type application/json false
Authorization Pointercrate access token false
If-Match Conditional request header. Needs to be set to the current etag value of the user object false
Field Type Description Optional
display_name string Set to update the users display name true
permissions bitmask Set to update the users permissions true

Response: 200 OK

Header Value
Content-Type application/json
ETag unsigned 64 bit hash of the updated user
Field Type Description
data User The updated user object

Response: 304 NOT MODIFIED

Returned when the PATCH operation did not make any changes.

Header Value
ETag unsigned 64 bit hash of the user

Errors:

Status code Error code Description
403 40303 Attempt to patch your own account through this endpoint

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 /

Access Restrictions:
Access to this endpoint requires at least Administrator permissions.

Deletes a user account. This action is irreversible!

Request:

Header Expected Value Optional
Authorization Pointercrate access token false
If-Match Conditional request header. Needs to be set to the current etag value of the user object false

Response: 204 NO CONTENT

Nothing

Errors:

| Status code | Error code | Description | | ----------- | ---------- | ----------------------------------------------------------------------------------------| |403|40302| Attempt to delete your own account through this endpoint| ### Example request:

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