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 permissions.

Allows to retrieve a potentially filtered list of all pointercrate users.

Filtering:

The result can be filtered by any of the following fields: id, name, 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 permissions.

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 base64 encoded 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 base64 encoded 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 permissions.

Modifies a given user.

Note that if you only have MODERATOR but not ADMINISTRATOR permissions, you can only modify a users display_name, not their permissions.

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

Request:

Header Expected Value Optional
Content-Type application/merge-patch+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 base64 encoded 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 base64 encoded hash of the user

Errors:

Status code Error code Description
400 40003 Invalid data type for requested field
403 40302 The requested field cannot be updated via this endpoint, or with your set of permissions
404 40401 No user with id user_id was found

Example request:

PATCH /api/v1/users/1/
     Accept: application/json
     Authorization: Bearer <omitted>
     Content-Type: application/merge-patch+json
     If-Match: JOa_QXhezgmqMWjzqD5rYXnHi3s=
     
     {
         "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 40300 Attempt to delete your own account. Use DELETE /auth/me/
404 40401 No user with id user_id was found
412 41200 The value provided in the If-Match header doesn't match the current state of the object
418 41800 No If-Match header was provided

Example request:

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