Auth API

Authentication endpoints for ryOS. These endpoints handle user registration, login, token management, and password operations.

Overview

The chat rooms authentication system uses token-based authentication with 90-day expiration. Users authenticate using:

Authorization: Bearer {token}
X-Username: {username}

Tokens are issued by /api/auth/register and /api/auth/login.

Most auth-protected endpoints now resolve credentials through the shared request-auth utility (both headers required together). register, login, and token/refresh remain explicit handlers.

Endpoint Summary

Endpoints

Register User

Create a new user account and receive an authentication token.

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

{
  "username": "alice",
  "password": "testpassword123"
}

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": { "username": "alice" }
}

Login

Authenticate with username and password.

POST /api/auth/login
Content-Type: application/json

{
  "username": "alice",
  "password": "testpassword123"
}

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "username": "alice"
}

Logout

Invalidate the current session token.

POST /api/auth/logout
Authorization: Bearer {token}
X-Username: alice

{
  "success": true,
  "message": "Logged out successfully"
}

Logout All Sessions

Invalidate all active tokens for the user.

POST /api/auth/logout-all
Authorization: Bearer {token}
X-Username: alice

{
  "success": true,
  "message": "Logged out from 2 devices",
  "deletedCount": 2
}

Verify Token

Check if a token is valid.

POST /api/auth/token/verify
Authorization: Bearer {token}
X-Username: alice

{
  "valid": true,
  "username": "alice",
  "message": "Token is valid"
}

If the token is in grace-period mode:

{
  "valid": true,
  "username": "alice",
  "expired": true,
  "message": "Token is within grace period"
}

Refresh Token

Get a new token before/after expiry (within grace period) using the old token.

POST /api/auth/token/refresh
Content-Type: application/json

{
  "username": "alice",
  "oldToken": "previous-token"
}

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Check Password Status

Check if a user has set a password.

GET /api/auth/password/check
Authorization: Bearer {token}
X-Username: alice

{
  "hasPassword": true,
  "username": "alice"
}

Set Password

Set or update the user's password.

POST /api/auth/password/set
Authorization: Bearer {token}
X-Username: alice
Content-Type: application/json

{
  "password": "newSecurePassword123"
}

{
  "success": true
}

List Active Tokens

Get all active session tokens for the user.

GET /api/auth/tokens
Authorization: Bearer {token}
X-Username: alice

{
  "tokens": [
    {
      "maskedToken": "...c0ffee12",
      "createdAt": 1704067200000,
      "isCurrent": true
    }
  ],
  "count": 1
}

Error Responses

Related

• Rooms API - Room endpoints

• Messages API - Message endpoints
• API Design Guide - API patterns and conventions