Authentication

OCVR uses session-based authentication with HMAC-signed opaque tokens. This page covers all auth-related endpoints.

Register

Create a new account.

POST /v1/auth/register

Request body:

{
  "email": "user@example.com",
  "password": "minimum8chars",
  "display_name": "DisplayName"
}

Response:

{
  "data": {
    "token": "sess_...",
    "user": {
      "id": 12345,
      "display_name": "DisplayName",
      "email": "user@example.com",
      "email_verified": false
    }
  }
}

Login

Authenticate an existing user.

POST /v1/auth/login

Request body:

{
  "email": "user@example.com",
  "password": "password123"
}

Response (no TOTP):

{
  "data": {
    "token": "sess_...",
    "user": { ... }
  }
}

Response (TOTP required):

{
  "data": {
    "totp_required": true,
    "totp_ticket": "totp_..."
  }
}

If TOTP is required, use the ticket to verify the code:

POST /v1/auth/totp/verify

{
  "ticket": "totp_...",
  "code": "123456"
}

Get Current User

GET /v1/auth/me
Authorization: Bearer sess_...

Response:

{
  "data": {
    "id": 12345,
    "display_name": "DisplayName",
    "email": "user@example.com",
    "email_verified": true,
    "bio": "Hello world",
    "status_text": "Playing OCVR",
    "is_superadmin": false
  }
}

Update Profile

PATCH /v1/auth/me
Authorization: Bearer sess_...

{
  "display_name": "NewName",
  "bio": "Updated bio",
  "status_text": "AFK"
}

Logout

Invalidate the current session.

POST /v1/auth/logout
Authorization: Bearer sess_...

Logout All Sessions

Invalidate all sessions for the current user.

POST /v1/auth/logout-all
Authorization: Bearer sess_...

List Sessions

Get all active sessions for the current user.

GET /v1/auth/sessions
Authorization: Bearer sess_...

Response:

{
  "data": {
    "sessions": [
      {
        "id": "sess_abc...",
        "created_at": 1703520000,
        "last_active_at": 1703523600,
        "ip_address": "192.168.1.1",
        "user_agent": "Mozilla/5.0...",
        "is_current": true
      }
    ]
  }
}

Revoke Session

DELETE /v1/auth/sessions/{sessionID}
Authorization: Bearer sess_...

Change Password

POST /v1/auth/change-password
Authorization: Bearer sess_...

{
  "current_password": "oldpassword",
  "new_password": "newpassword123"
}

TOTP (Two-Factor Authentication)

Check TOTP Status

GET /v1/auth/totp/status
Authorization: Bearer sess_...

Setup TOTP

POST /v1/auth/totp/setup
Authorization: Bearer sess_...

Returns a secret and QR code URL for authenticator apps.

Enable TOTP

POST /v1/auth/totp/enable
Authorization: Bearer sess_...

{
  "code": "123456"
}

Disable TOTP

POST /v1/auth/totp/disable
Authorization: Bearer sess_...

{
  "code": "123456"
}

Get Backup Codes

POST /v1/auth/totp/backup-codes
Authorization: Bearer sess_...

Error Codes

Code	Description
AUTH_INVALID_CREDENTIALS	Wrong email or password
AUTH_TOKEN_EXPIRED	Session has expired
AUTH_TOTP_REQUIRED	TOTP code needed
AUTH_TOTP_INVALID	Wrong TOTP code
AUTH_EMAIL_TAKEN	Email already registered