POST /auth/login

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

Rate Limiting

This endpoint is protected by rate limiting. After 10 failed login attempts within a 15-minute window (configurable in the backend), further attempts are temporarily blocked.

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

429 Too Many Requests

Returned when too many failed login attempts are made within a short period of time. The client is temporarily blocked from making further login requests.

{
    "data": "Too many requests.",
    "code": 429
}

Models used
Response Model

POST /auth/register

Registers a new user account using a username and password.

Rate Limiting

This endpoint is protected by rate limiting. After 10 register attempts within a 1-hour window (configurable in the backend), further attempts are temporarily blocked.

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

During registration, the backend validates both the username and password against rules defined in the backend configuration. The username must be a string that falls within the allowed length range and matches the permitted character set, ensuring only valid characters are accepted. The password is also validated to confirm it is a string and meets the configured length requirements. If any of these checks fail, the registration request is rejected with a validation error.

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

429 Too Many Requests

Returned when too many failed register attempts are made within a short period of time. The client is temporarily blocked from making further register requests.

{
    "data": "Too many requests.",
    "code": 429
}

Models used
Response Model

500 Internal Server Error

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

{
    "data": "User creation failed",
    "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 CDN Next User