Registering for an account

POST /auth/register/

Rate Limits:
This endpoint is ratelimited at 1 successful request per day and at 5 failed requests per 6 hours

Registers a new pointercrate account.

When registering, you only choose your username and your password. Your chosen username must be at least 3 spaces long and may not contain leading or trailing spaces. Your chosen password must be at least 10 characters long and has no further restrictions imposed.

The username isn’t changeable afterward, but you can set your display_name to nearly any value you want via PATCH /auth/me/.

Registering for an account does not provide an access token, it needs to be acquired by using the login endpoint.

Request

Header Expected Value Optional
Content-Type application/json false
Field Type Description Optional
name string Your username false
password string Your password false

Response: 201 CREATED

Header Value
Content-Type application/json
Location /auth/me/
ETag hash of your user object
Field Type Description
data User A user object representing your newly registered account

Errors

Status code Error code Description
409 40902 The chosen name is already in use
422 42202 The chosen name does not meet the above mentioned criteria
422 42204 The chosen password is too short

Example request

POST /api/v1/auth/register/
Accept: application/json
Content-Type: application/json

{
"name": "stadust",
"password": "password123"
}

Login to a pointercrate account

POST /auth/

Rate Limits:
This endpoint is ratelimited at 3 requests per 30 minutes

Logs into an existing pointercrate user account, providing an access token upon success.

Request:

Header Expected Value Optional
Authorization Basic access authentication header false

Response: 200 OK

Header Value
Content-Type application/json
ETag unsigned 64 bit hash of your user object
Field Type Description
data User A user object representing the account you just logged into
token Pointercrate access token Your access token to use when performing requests to the pointercrate api

Example request:

POST /api/v1/auth/
Accept: application/json
Authorization: Basic <omitted>

Invalidating access tokens

POST /auth/invalidate/

Invalidates all access tokens to your account.

Request:

Header Expected Value Optional
Authorization Basic access authentication header false

Response: 204 NO CONTENT

Nothing

Example request

POST /api/v1/auth/invalidate/
Accept: application/json
Authorization: Basic <omitted>

Retrieve account information

GET /auth/me/

Gets information about the currently logged in account (that is, the account whose access token is sent).

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 your user object
Field Type Description
data User A user object representing the account you just logged into

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 your user object

Example request:

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

Modifying your account

PATCH /auth/me/

Modifies the currently logged in account (that is, the account whose credentials are sent).

Note that after updating your password, you will have to log in again, as changing passwords invalidates access tokens.

Modifying your account requires you to provide your password instead of just an access token, to ensure that if you for some reason leak your access token, other people at least cannot change your password, allowing you to invalidate the leaked token by doing so yourself.

Request:

Header Expected Value Optional
Content-Type application/json false
Authorization Basic access authentication header false
If-Match Conditional request header. Needs to be set to the current etag value of the user object false
Field Type Description Optional
password string Set to update your password true
display_name string Set to update your diplay name. Set to null to reset it true
youtube_channel string Set to update the link to your youtube channel displayed along with your name true

Response: 200 OK or 204 NO CONTENT

In case the password was changed, a 204 is returned and the user has to reauthenticate. Otherwise, a 200 response is generated.

Header Value
Content-Type application/json
ETag unsigned 64 bit hash of your user object
Field Type Description
data User A user object representing the account you just logged into

Response: 304 NOT MODIFIED

Returned when the PATCH operation did not make any changes. Note that this is also returned when you only change your password, as you hashed password is not part of your user object hash.

Header Value
ETag unsigned 64 bit hash of your user object

Errors:

Status code Error code Description Data
422 42202 The choosen name does not meet the criteria described here -
422 42204 The choosen password is too short -
422 42225 The channel URL does not match the expected format expected: The expected URL format
422 42226 The provided channel URL isn’t a YouTube URL -

Example request:

PATCH /api/v1/auth/me/
Accept: application/json
Authorization: Basic <omitted>
Content-Type: application/json
If-Match: 10434480491831244259

{
    "display_name": "stardust1971",
    "password": "password1234"
}

Deleting your account

DELETE /auth/me/

Deletes your pointercrate account. Note that this action is irreversible!

Deleting your account requires you to provide your password instead of just an access token, to ensure that if you for some reason leak your access token, other people at least cannot delete your account.

Request

Header Expected Value Optional
Authorization Basic access authentication header 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

Example request

DELETE /api/v1/auth/me/
Accept: application/json
Authorization: Basic <omitted>
If-Match: 10434480491831244259