Skip to main content
Manage user accounts, authentication, and profiles.

​
Get Current User

​
GET /api/user

Get information about the current user associated with the authentication token. Authentication: Required 
curl https://opentogethertube.com/api/user \
  -H "Authorization: Bearer YOUR_TOKEN"
Response (Logged In)
​
username
string
User’s username
​
loggedIn
boolean
Whether the user is logged into an account
​
discordLinked
boolean
Whether the user has linked their Discord account
{
  "username": "john_doe",
  "loggedIn": true,
  "discordLinked": true
}
Response (Not Logged In) 
{
  "username": "guest-swift-otter",
  "loggedIn": false
}

​
Update Username

​
POST /api/user

Update the username for the current session. Authentication: Required Request Body
​
username
string
required
New username (max 20 characters)
curl -X POST https://opentogethertube.com/api/user \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "new_username"}'
Response 
{
  "success": true
}
Error: Username Taken 
{
  "success": false,
  "error": {
    "name": "UsernameTaken",
    "message": "Somebody else is already using that username."
  }
}

​
Register Account

​
POST /api/user/register

Register a new user account. Authentication: Required (token will be upgraded to registered session) Request Body
​
username
string
required
Desired username
​
email
string
required
Email address
​
password
string
required
Password
curl -X POST https://opentogethertube.com/api/user/register \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john_doe",
    "email": "[email protected]",
    "password": "securepassword123"
  }'
Response
​
success
boolean
Operation status
​
user
object
Created user information
​
user.username
string
Username
​
user.email
string
Email address
{
  "success": true,
  "user": {
    "username": "john_doe",
    "email": "[email protected]"
  }
}
Error Response 
{
  "success": false,
  "error": {
    "name": "ValidationError",
    "message": "Username is already taken",
    "fields": ["username"]
  }
}

​
Login

​
POST /api/user/login

Log into an existing account. Authentication: Required (token will be upgraded to registered session) Request Body
​
email
string
required
Email address
​
password
string
required
Password
​
username
string
Optional username (for backwards compatibility)
curl -X POST https://opentogethertube.com/api/user/login \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securepassword123"
  }'
Response 
{
  "success": true,
  "user": {
    "username": "john_doe",
    "email": "[email protected]"
  }
}
Error Response (Invalid Credentials) 
{
  "success": false,
  "error": {
    "name": "AuthenticationError",
    "message": "Invalid email or password"
  }
}
Login attempts are rate-limited:
  • 100 attempts per IP per day
  • 10 consecutive failed attempts per username/IP combination blocks access for 1 hour

​
Logout

​
POST /api/user/logout

Log out of the current account session. Authentication: Required 
curl -X POST https://opentogethertube.com/api/user/logout \
  -H "Authorization: Bearer YOUR_TOKEN"
Response 
{
  "success": true
}
After logout, the token remains valid but is no longer associated with the logged-in user account. A new guest username is assigned.

​
Get Owned Rooms

​
GET /api/user/owned-rooms

Get all permanent rooms owned by the currently logged-in user. Authentication: Required (must be logged in) 
curl https://opentogethertube.com/api/user/owned-rooms \
  -H "Authorization: Bearer YOUR_TOKEN"
Response
​
success
boolean
Operation status
​
data
array
Array of owned rooms
{
  "success": true,
  "data": [
    {
      "name": "my-room",
      "title": "My Personal Room",
      "description": "A room I created",
      "isTemporary": false,
      "visibility": "public",
      "queueMode": "manual",
      "currentSource": null,
      "users": 0
    }
  ]
}
Error Response (Not Logged In) 
{
  "success": false,
  "error": {
    "name": "Unauthorized",
    "message": "Not logged in."
  }
}

​
Account Recovery

​
POST /api/user/recover/start

Initiate account recovery process. Request Body
​
email
string
required
Email address associated with the account
curl -X POST https://opentogethertube.com/api/user/recover/start \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'
Response 
{
  "success": true
}
A recovery email is sent to the address if an account exists.

​
POST /api/user/recover/verify

Complete account recovery with verification key. Request Body
​
email
string
required
Email address
​
verifyKey
string
required
Verification key from recovery email
​
password
string
required
New password
curl -X POST https://opentogethertube.com/api/user/recover/verify \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "verifyKey": "abc123...",
    "password": "newpassword123"
  }'
Response 
{
  "success": true
}

​
OAuth (Discord)

​
GET /api/user/auth/discord

Initiate Discord OAuth flow for linking Discord account. 
curl https://opentogethertube.com/api/user/auth/discord
Redirects to Discord authorization page.

​
GET /api/user/auth/discord/callback

Discord OAuth callback. Handled automatically by the server.

​
Common Error Responses

​
Rate Limited

{
  "success": false,
  "error": {
    "name": "RateLimitError",
    "message": "Too many requests. Try again later."
  }
}

​
Validation Error

{
  "success": false,
  "error": {
    "name": "ValidationError",
    "message": "Invalid input",
    "fields": ["email", "password"]
  }
}

​
Length Out of Range

{
  "success": false,
  "error": {
    "name": "LengthOutOfRangeException",
    "message": "Username length must be less than or equal to 20"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us