POST /auth/login

Authenticates a user using a username and password, then issues JWT tokens for session management.

Request Body

The request body must be sent as JSON and include the following fields:

Field Type Required Description
username string Yes The user’s username
password string Yes The user’s plain-text password

Example

{
  "username": "exampleUser",
  "password": "securePassword123"
}

Responses

200 OK

Returned when the user is authenticated successfully.

{
    "accessToken": "<jwt-access-token>",
    "user": {
        "id": "string",
        "username": "string",
        "profile_image": "string | null",
        "registered": "string",
        "age_verified": "number",
        "slug": "string",
        "roles": [/* See model for reference */],
        "permissions": [/* See model for reference */],
    }
}

Models used
User Model
Role Model
Permission Model

400 Bad Request

Returned when required request parameters are missing.

{
    "data": "Required parameters missing",
    "code": 400
}

Models used
Response Model

401 Unauthorized

Returned when the username does not exist or the password is incorrect.

{
    "data": "Invalid credentials",
    "code": 401
}

Models used
Response Model

POST /auth/register

Registers a new user account using a username and password.

Request Body

The request body must be sent as JSON and include the following fields:

Field Type Required Description
username string Yes Desired username
password string Yes Plain-text account password

Example

{
  "username": "new_user",
  "password": "strongPassword123"
}

Responses

201 Created

Returned when the user account is created successfully.

{
  "data": "User created successfully",
  "code": 201
}

Models used
Response Model

400 Bad Request

Returned when required request parameters are missing.

{
    "data": "Required parameters missing",
    "code": 400
}

Models used
Response Model

409 Conflict

Returned when the requested username is already in use.

{
    "data": "Username already taken",
    "code": 409
}

Models used
Response Model

422 Unprocessable Entity

Returned when the username or password does not meet validation requirements.

{
    "data": "Invalid username",
    "code": 422
}

{
    "data": "Invalid password",
    "code": 422
}

Models used
Response Model

500 Internal Server Error

Returned when an internal error occurs during user creation or role assignment.

{
    "data": "Error creating user",
    "code": 500
}

{
    "data": "Error assigning role to user",
    "code": 500
}

{
    "data": "No default role set",
    "code": 500
}

Models used
Response Model

GET /auth/me

Validates the current user session using a refresh token and returns the authenticated user context along with a newly issued access token.

Authentication

This endpoint uses the refresh token stored in cookies.

Cookie Name Required Description
refreshToken Yes Refresh token used to validate user

Responses

200 OK

Returned when the user is authenticated successfully and the session is valid.

{
    "accessToken": "<jwt-access-token>",
    "user": {
        "id": "string",
        "username": "string",
        "profile_image": "string | null",
        "registered": "string",
        "age_verified": "number",
        "slug": "string",
        "roles": [/* See model for reference */],
        "permissions": [/* See model for reference */],
        "settings": { /* User-specific settings */ }
    }
}

Models used
User Model
Role Model
Permission Model

401 Unauthorized

Returned when the refresh token is missing, invalid, or does not resolve to a user.

{
    "data": "Unauthorized",
    "code": 401
}

Models used
Response Model

POST /auth/logout

Logs out the currently authenticated user by invalidating the refresh token and clearing the authentication cookie.

Authentication

This endpoint uses the refresh token stored in cookies.

Cookie Name Required Description
refreshToken Yes Refresh token used to identify user

Responses

200 OK

Returned when the user is logged out successfully.

{
    "data": "Logged out",
    "code": 200
}

Models used
Response Model

401 Unauthorized

Returned when the refresh token is missing or invalid.

{
    "data": "Unauthorized",
    "code": 401
}

Models used
Response Model

Previous User Model