Docs.md

Authentication System API Documentation

Base URL

/v1/api

Authentication Routes

1. Sign Up

Creates a new user account.

Endpoint: POST /auth/signup

Request Body:

{
  "username": "string",
  "password": "string",
  "email": "string (optional)"
}

Response (201 Created):

{
  "message": "User created successfully"
}

Possible Errors:

• 400 Bad Request: Username already exists

2. Login

Authenticates a user and creates a new session.

Endpoint: POST /auth/login

Headers:

• user-agent: Browser/device user agent string (required)

Request Body:

{
  "username": "string",
  "password": "string"
}

Response (200 OK):

{
  "user_id": "string",
  "username": "string",
  "email": "string",
  "access_level": "string",
  "date_joined": "datetime",
  "access_token": "string",
  "token_type": "bearer"
}

Possible Errors:

• 401 Unauthorized: Invalid credentials

3. Logout

Terminates an active session.

Endpoint: POST /auth/logout

Query Parameters:

• user_id: string
• token: string

Response (200 OK):

{
  "message": "Session forcefully expired"
}

Possible Errors:

• 400 Bad Request: No active sessions

4. Validate Token

Validates an existing session token.

Endpoint: GET /auth/validate

Headers:

• user-agent: Browser/device user agent string (required)

Query Parameters:

• user_id: string
• token: string

Response (200 OK):

{
  "access_token": "string",
  "token_type": "bearer"
}

Possible Errors:

• 401 Unauthorized: No active sessions, Device mismatch, Token expired, Invalid token

5. Search Users

Search for users by username.

Endpoint: GET /auth/search-users

Query Parameters:

• query: string

Response (200 OK):

[
  "string"
]

6. Get User ID

Retrieve user ID by username.

Endpoint: GET /auth/get-user-id

Query Parameters:

• username: string

Response (200 OK):

"string" (user_id)

Possible Errors:

• 404 Not Found: Username not found

7. Update Own Data

Update authenticated user's information.

Endpoint: PUT /auth/user/update

Headers:

• token: string
• user-agent: Browser/device user agent string (required)

Query Parameters:

• user_id: string

Request Body:

{
  "password": "string (optional)",
  "email": "string (optional)",
  "username": "string (optional)"
}

Response (200 OK):

{
  "username": "string",
  "email": "string",
  "access_level": "string",
  "date_joined": "datetime"
}

Admin Routes

1. Get All Users

Retrieve all users (requires HUSH access level).

Endpoint: GET /admin/users

Headers:

• user-agent: Browser/device user agent string (required)

Query Parameters:

• user_id: string (admin's user ID)
• token: string

Response (200 OK):

[
  {
    "username": "string",
    "email": "string",
    "access_level": "string",
    "date_joined": "datetime"
  }
]

Possible Errors:

• 403 Forbidden: Insufficient permissions

2. Get User Details

Retrieve specific user details (requires HUSH access level).

Endpoint: GET /admin/user/{user_id}

Headers:

• user-agent: Browser/device user agent string (required)

Query Parameters:

• admin_id: string
• token: string

Response (200 OK):

{
  "username": "string",
  "email": "string",
  "access_level": "string",
  "date_joined": "datetime"
}

3. Update User

Update user information (requires HUSH access level).

Endpoint: PUT /admin/user/{user_id}

Headers:

• user-agent: Browser/device user agent string (required)

Query Parameters:

• admin_id: string
• token: string

Request Body:

{
  "password": "string (optional)",
  "email": "string (optional)",
  "username": "string (optional)"
}

4. Update Access Level

Update user access level (requires HUSH access level).

Endpoint: PUT /admin/user/{user_id}/access-level

Headers:

• user-agent: Browser/device user agent string (required)

Query Parameters:

• admin_id: string
• token: string

Request Body:

{
  "access_level": "string"
}

Access Levels

The system supports the following access levels in ascending order of privileges:

1. default
2. member
3. admin
4. dev
5. hush

Notes

• All timestamps are in UTC
• Token expiration is set to 60 minutes
• Sessions are device-specific and validated against the user agent
• Database changes are saved to disk in debug mode
• The system automatically creates a HUSH-level system user on startup