# Auth API Documentation **Server**: `apps/api/api.ts` **Port**: 3009 **Purpose**: Public-facing authentication and media services server ## Overview The Auth API is the main public-facing API server that handles: - User authentication (email/password, Steam, Oculus) - Account management - Media and entitlements - TV channels and topics - Beyond (custom cushion) services - Analytics and reporting ## Authentication ### Required Headers All endpoints (except `/shopify/webhook`) require: ``` Authorization: ``` Most endpoints also require: ``` Authorization: Bearer ``` ### Rate Limiting Rate limiting is applied to authentication endpoints to prevent abuse. --- ## Endpoints ### Authentication & Login #### Create Account with Email/Password ``` POST /auth/account ``` **Body**: `{ email, password, username, ... }` **Returns**: New account with access token #### Create Account from Steam ``` POST /auth/steam/account ``` **Body**: `{ steamId, steamTicket, ... }` **Returns**: New account with access token #### Create Account from Oculus ``` POST /auth/oculus/account ``` **Body**: `{ oculusId, oculusNonce, ... }` **Returns**: New account with access token #### Login with Email/Password ``` POST /auth/login ``` **Body**: `{ email, password }` **Returns**: Access token and refresh token #### Login with Oculus ``` POST /auth/oculus/login ``` **Body**: `{ oculusId, oculusNonce }` **Returns**: Access token and refresh token #### Login with Steam ``` POST /auth/steam/login ``` **Body**: `{ steamId, steamTicket }` **Returns**: Access token and refresh token #### Logout ``` GET /auth/logout ``` **Auth**: Access token required **Returns**: Success confirmation #### Verify Token ``` GET /auth/verify ``` **Auth**: Access token required **Returns**: Token validity status #### Renew Access Token ``` GET /auth/renew ``` **Query**: `refreshToken`, `nonce` **Returns**: New access token #### Who Am I ``` GET /auth/whoami ``` **Auth**: Bearer token required **Returns**: Authentication status #### Login with Single-Use Token ``` GET /auth/token/login/:singleUseLoginToken ``` **Returns**: Access token #### Login with Token (v2) ``` GET /auth/token2/login/:publicToken ``` **Returns**: Access token #### Verify Oculus Nonce (Dev Only) ``` POST /auth/oculus/verify ``` **Body**: `{ oculusId, oculusNonce }` **Returns**: Verification result --- ### Account Management #### Get Current User Profile ``` GET /auth/account GET /auth/profile (alias) ``` **Auth**: Access token required **Returns**: User account details #### Update Account ``` PUT /auth/account ``` **Auth**: Access token required **Body**: Account fields to update **Returns**: Updated account #### Attach Email/Password to Account ``` POST /auth/account/attach ``` **Auth**: Access token required **Body**: `{ email, password }` **Returns**: Updated account #### Attach Steam Account ``` POST /auth/steam/attach ``` **Auth**: Access token required **Body**: `{ steamId, steamTicket }` **Returns**: Updated account #### Detach Steam Account ``` POST /auth/steam/detach ``` **Auth**: Access token required **Returns**: Updated account #### Get Device Info ``` GET /auth/device/:deviceUniqueIdentifier ``` **Auth**: Access token required **Returns**: Device information #### Get Account Feature Flags ``` GET /auth/account/flags ``` **Auth**: Access token required **Returns**: Feature flags for the account --- ### Password Reset & Email Verification #### Request Password Reset ``` POST /auth/forgot ``` **Body**: `{ email }` **Returns**: Confirmation (email sent) #### Verify Reset Token ``` GET /auth/reset/:resetPasswordToken ``` **Returns**: Token validity #### Reset Password ``` POST /auth/reset ``` **Body**: `{ resetPasswordToken, newPassword }` **Returns**: Success confirmation #### Verify Email ``` GET /auth/email/verify/:token ``` **Returns**: Email verification result #### Update Email ``` GET /auth/email/update/:emailUpdateToken ``` **Returns**: Email update confirmation #### Resend Confirmation Email ``` GET /auth/resend ``` **Auth**: Access token required **Returns**: Confirmation (email sent) --- ### Public Info & Utility #### Get Public Profile ``` GET /info/account/:field/:value ``` **Params**: `field` (username or userSessionId), `value` **Returns**: Public profile information #### Get Profile by Username ``` GET /info/username/:username ``` **Returns**: Public profile or username availability #### Filter Room Input ``` PUT /info/room/:roomId/sanitize ``` **Body**: Text to sanitize **Returns**: Filtered text #### Sentiment Analysis ``` PUT /info/room/:roomId/sentiment ``` **Body**: Text to analyze **Returns**: Sentiment score #### Get Server Timestamp ``` GET /info/timestamp ``` **Returns**: Current server timestamp #### Get User Region ``` GET /info/region ``` **Returns**: User's IP region code #### Get User Currency ``` GET /info/currency ``` **Returns**: User's currency code based on location --- ### Beyond (Custom Cushion) APIs #### Get Pending Scans ``` GET /beyond/scans GET /beyond/scans/:scanRequestState ``` **Auth**: Access token required **Returns**: User's scan requests #### Check Customer ID ``` GET /beyond/topology/:topologyToken ``` **Returns**: Whether customer ID exists #### Process Scan ``` GET /beyond/scan/:topologyToken/process ``` **Returns**: Scan processing result #### Get Shopify Multipass URL ``` GET /beyond/multipass ``` **Auth**: Access token required **Returns**: Shopify authentication URL #### Get Orders ``` GET /beyond/orders ``` **Auth**: Access token required **Returns**: User's Beyond orders #### Get Specific Order ``` GET /beyond/order/:bigOrderId ``` **Auth**: Access token required **Returns**: Order details #### Set IPD for Order ``` PUT /beyond/order/:bigOrderId/ipd ``` **Auth**: Access token required **Body**: `{ ipd }` **Returns**: Updated order #### Get Scan Request ``` GET /beyond/scan/:scanRequestId ``` **Auth**: Access token required **Returns**: Scan request details #### Request Rescan ``` PUT /beyond/scan/:scanRequestId/rescan ``` **Auth**: Access token required **Returns**: Updated scan request --- ### TV Channels & Topics #### Get Public Channel Groups ``` GET /channel_groups ``` **Returns**: List of public channel groups #### Get Channel Group ``` GET /channel_group/:name ``` **Returns**: Channel group details #### Get Channel ``` GET /channel/:channelId ``` **Returns**: Channel information #### Get Topic ``` GET /topic/:topicName ``` **Auth**: Access token required **Returns**: Topic details #### Subscribe to Topic ``` GET /topic/:topicName/subscribe ``` **Auth**: Access token required **Returns**: Subscription confirmation #### Unsubscribe from Topic ``` GET /topic/:topicName/unsubscribe ``` **Auth**: Access token required **Returns**: Unsubscription confirmation --- ### Media & Entitlements #### Get Category ``` GET /media/category/:name ``` **Returns**: Media category #### Get Categories After Date ``` GET /media/categories/:name/:after ``` **Returns**: Categories updated after date #### Get Categories as Events ``` GET /media/categories_as_events/:name ``` **Returns**: Categories formatted as events #### Get Media Product ``` GET /media/product/:bigMediaId ``` **Returns**: Product details #### Get Account Location ``` GET /media/location ``` **Auth**: Access token required **Returns**: Account location for pricing #### Get Entitlements ``` GET /media/entitlements GET /media/entitlements/:bigMediaId ``` **Auth**: Access token required **Returns**: User's media entitlements #### Get Entitlements Checksum ``` GET /media/checksum ``` **Auth**: Access token required **Returns**: Checksum for caching #### Check Media Access ``` GET /media/check/:bigMediaId ``` **Auth**: Access token required **Returns**: Access permission #### Get Playback Manifest ``` GET /media/play/:bigMediaId ``` **Auth**: Access token required **Returns**: Playback information #### Find Media Stream ``` GET /media/start/:mediaRequest ``` **Auth**: Access token required **Returns**: Stream URL #### Send Purchase Email ``` GET /media/token/purchase/:bigMediaId ``` **Auth**: Access token required **Returns**: Purchase email sent #### Auto-Order Free Items ``` POST /media/try-automatic-order ``` **Auth**: Access token required **Body**: `{ bigMediaId }` **Returns**: Order result #### Purchase Item (Stripe) ``` POST /media/order ``` **Auth**: Access token required **Body**: Payment details **Returns**: Order confirmation #### Create Free Entitlement ``` PUT /media/entitlement/:entitlementClass ``` **Auth**: Access token required **Returns**: New entitlement #### Activate Browser Entitlement ``` PUT /media/entitlement/:entitlementId/activate ``` **Auth**: Access token required **Returns**: Activated entitlement #### Get Browser Entitlements (Deprecated) ``` GET /media/entitlement/browser ``` **Auth**: Access token required **Returns**: Browser entitlements #### Get Feature Flag Entitlements ``` GET /media/entitlement/features ``` **Auth**: Access token required **Returns**: Feature entitlements #### Create Oculus IAP Order ``` POST /media/oculus/order ``` **Auth**: Access token required **Body**: Oculus purchase details **Returns**: Order confirmation #### Update Oculus Purchases ``` POST /media/oculus/update ``` **Auth**: Access token required **Returns**: Updated entitlements #### Get Purchase Receipts ``` GET /media/receipts ``` **Auth**: Access token required **Returns**: Purchase history #### Get Media Info ``` GET /media/info/:mediaRequest ``` **Returns**: Media metadata #### Send Media Engagement Analytics ``` GET /media/analytics/engagement/:videoPosition ``` **Auth**: Access token required **Query**: Media engagement data **Returns**: Success confirmation --- ### Analytics #### Create Analytics Event ``` POST /event ``` **Auth**: Access token required **Body**: Event data **Returns**: Success confirmation --- ### Reporting #### Report User ``` POST /report/user ``` **Auth**: Cloud API restricted **Body**: Report details **Returns**: Report ID #### Report Room ``` POST /report/room ``` **Auth**: Cloud API restricted **Body**: Report details **Returns**: Report ID --- ### Webhooks #### Shopify Webhook ``` POST /shopify/webhook ``` **Auth**: None (Shopify signature verification) **Body**: Shopify webhook payload **Returns**: Processing confirmation --- ## Source Code - **Main server**: `apps/api/api.ts` - **Tests**: `tests/api/` ## Related Documentation - [API Overview](API_OVERVIEW.md) - [Admin API](ADMIN_API.md) - [Cloud API](CLOUD_API.md)