Authentication API¶

This document describes all authentication and LiveKit endpoints, organized by access level.

Public Endpoints¶

These endpoints are accessible without authentication.

Initiates the authentication process for existing users.

Endpoint: POST /auth/sign-in

Request Body:

{
  "email": "jane.doe@example.com"
}

Success Response (SSO): 200 OK

{
  "authData": {
    "authMethod": "sso",
    "redirectURL": "https://api.workos.com/sso/authorize?client_id=...",
    "state": "a_random_state_string_for_security"
  }
}

Success Response (Magic Auth): 200 OK

{
  "authData": {
    "authMethod": "magic_auth"
  }
}

Error Response: 400 Bad Request

{
  "code": 400,
  "message": "Bad request"
}

Testing Only

This endpoint is for development and testing purposes only. Do not use in production.

Endpoint: POST /auth/dev-sign-in

Request Body:

{}

Success Response: 200 OK

{
  "user": {
    "id": "user_01HCNYK4PEV6Y1EDZ8EAZG1A1B",
    "email": "admin@cazzi.com"
  }
}

Creates a new user account.

Endpoint: POST /auth/sign-up

Request Body:

{
  "email": "new.user@example.com"
}

Success Response: 201 Created

{
  "code": 201,
  "message": "Created"
}

Finalize OAuth¶

Completes the OAuth authentication flow.

Endpoint: POST /auth/finalize-oauth

Request Body:

{
  "code": "FHN398YTN3904T309M"
}

Success Response: 200 OK

{
  "user": {
    "id": "user_01HCNYK4PEV6Y1EDZ8EAZG1A1B",
    "email": "johndoe@abc.com",
    "firstName": "John",
    "lastName": "Doe",
    "avatarURL": "https://example.com/avatar.png"
  }
}

Resend Magic Auth¶

Resends the magic authentication code to the user's email.

Endpoint: POST /auth/resend-magic-auth

Request Body:

{
  "email": "user.with.magic.auth@example.com"
}

Success Response: 200 OK

{
  "code": 200,
  "message": "OK"
}

Finalize Magic Auth¶

Completes the magic link authentication flow.

Endpoint: POST /auth/finalize-magic-auth

Request Body:

{
  "email": "user.with.magic.auth@example.com",
  "code": "123456"
}

Success Response (Single Organization): 200 OK

{
  "user": {
    "id": "user_01HCNYK4PEV6Y1EDZ8EAZG1A1B",
    "email": "johndoe@abc.com",
    "firstName": "John",
    "lastName": "Doe",
    "avatarURL": "https://example.com/avatar.png"
  }
}

Success Response (Multiple Organizations): 200 OK

When a user belongs to multiple organizations, they must select one to continue.

{
  "user": {
    "id": "user_01JY16X8FCYMX981HC4GYQ6S01",
    "email": "123@gmail.com",
    "pendingAuthenticationToken": "uMc1tPo4wDjpsnb2mEZlOv8KD",
    "organizations": [
      {
        "id": "org_01K2Z1R2MEJK6B41WW7428G9YC",
        "name": "MASADAS"
      },
      {
        "id": "org_01K3BK4YS5SDH22RV4P9QYJR7Z",
        "name": "TAUNTA SCRE"
      }
    ]
  }
}

Continue with Google¶

Initiates Google OAuth authentication flow.

Endpoint: POST /auth/continue-with-google

Request Body: None

Success Response: 200 OK

{
  "authData": {
    "redirectURL": "https://yourapp.com/redirecturl",
    "state": "xyz123stateToken"
  }
}

Continue with Microsoft¶

Initiates Microsoft OAuth authentication flow.

Endpoint: POST /auth/continue-with-microsoft

Request Body: None

Success Response: 200 OK

{
  "authData": {
    "redirectURL": "https://yourapp.com/redirecturl",
    "state": "xyz123stateToken"
  }
}

Select Organization¶

Selects an organization after authentication when user belongs to multiple organizations.

Endpoint: POST /auth/select-organization

Request Body:

{
  "pendingAuthenticationToken": "KcFtu30FfyJUfyeeaTwKwU02P",
  "organizationId": "org_01K3BK4YS5SDH22RV4P9QYJR7Z"
}

Success Response: 200 OK

{
  "user": {
    "id": "user_01HCNYK4PEV6Y1EDZ8EAZG1A1B",
    "email": "johndoe@abc.com",
    "firstName": "John",
    "lastName": "Doe",
    "avatarURL": "https://example.com/avatar.png"
  }
}

Switch Organization¶

Switches the active organization for an authenticated user.

Endpoint: POST /auth/switch-organization

Request Body:

{
  "email": "johndoe@abc.com",
  "organizationId": "org_01K2Z1R2MEJK6B41WW7428G9YC"
}

Success Response: 200 OK

{
  "user": {
    "id": "user_01HCNYK4PEV6Y1EDZ8EAZG1A1B",
    "email": "johndoe@abc.com",
    "firstName": "John",
    "lastName": "Doe",
    "avatarURL": "https://example.com/avatar.png"
  }
}

Protected Endpoints¶

These endpoints require authentication. Include a valid session token in the request.

Sign Out¶

Signs out the authenticated user.

Endpoint: POST /auth/sign-out

Request Body: None

Success Response: 200 OK

{
  "authData": {
    "redirectURL": "https://api.workos.com/user_management/sessions/logout?return_to=...&session_id=session_01JZG38PH9VWFRMCXZB8M5B6SR"
  }
}

Avatar Upload Ticket¶

Generates a presigned URL for direct avatar upload to R2 storage.

Endpoint: POST /auth/avatar/upload-ticket

Request Body:

{
  "contentType": "image/webp"
}

Allowed Content Types: - image/jpeg - image/png - image/webp

Success Response: 200 OK

{
  "code": 200,
  "message": "OK",
  "data": {
    "uploadUrl": "https://<account>.r2.cloudflarestorage.com/bucket/tmp/user123/abc.webp?X-Amz-Algorithm=...",
    "tmpKey": "tmp/user123/550e8400-e29b-41d4-a716-446655440000.webp",
    "expiresInSeconds": 120
  }
}

Error Responses:

Status	Condition
400	Unsupported content type
401	Missing or invalid authentication
422	Request validation failed
500	Failed to generate presigned URL

Notes:

After receiving the presigned URL, upload the image directly to R2 using a PUT request:

curl -X PUT "<uploadUrl>" \
  -H "Content-Type: image/webp" \
  --data-binary @avatar-image.webp

Avatar Finalize¶

Validates and promotes an uploaded avatar to permanent storage, updates user profile.

Endpoint: POST /auth/avatar/finalize

Request Body:

{
  "tmpKey": "tmp/user123/550e8400-e29b-41d4-a716-446655440000.webp"
}

Success Response: 200 OK

{
  "code": 200,
  "message": "OK",
  "avatarUrl": "https://avatars.qubital.space/avatars/user123/550e8400-e29b-41d4-a716-446655440000.webp"
}

Error Responses:

Status	Condition
400	Invalid image (corrupt, wrong format, wrong dimensions)
401	Missing or invalid authentication
403	tmpKey doesn't belong to authenticated user
404	Upload not found (expired or never uploaded)
422	Request validation failed
500	Internal error (R2 operation failed, WorkOS update failed)

LiveKit Room Authorization¶

Generates an access token for joining a LiveKit room.

Endpoint: POST /api/v1/livekit/room-auth

Request Body:

{
  "username": "Jane Doe",
  "roomId": "room123"
}

Success Response: 200 OK

{
  "token": "livekitToken"
}

Start Recording¶

Starts recording a LiveKit room session.

Endpoint: POST /api/v1/livekit/start-recording

Request Body:

{
  "roomName": "test-room",
  "conferenceTopic": "Weekly Sync Meeting",
  "zoneId": "1",
  "participants": "alice,bob,charlie"
}

Success Response: 200 OK

{
  "egressId": "egress-456789",
  "timestamp": 1752486896
}

Stop Recording¶

Stops an active LiveKit room recording.

Endpoint: POST /api/v1/livekit/stop-recording

Request Body:

{
  "roomName": "test-room",
  "egressId": "egress-456789",
  "zoneId": "1"
}

Success Response: 200 OK

{
  "egressId": "egress-456789",
  "timestamp": 1752486896
}

Authentication API¶

Public Endpoints¶

Sign In¶

Dev Sign In¶

Sign Up¶

Finalize OAuth¶

Resend Magic Auth¶

Finalize Magic Auth¶

Continue with Google¶

Continue with Microsoft¶

Select Organization¶

Switch Organization¶

Protected Endpoints¶

Sign Out¶

Avatar Upload Ticket¶

Avatar Finalize¶

LiveKit Room Authorization¶

Start Recording¶

Stop Recording¶