Overview
For BloxChat to work, your Roblox game must integrate with the backend to complete the verification flow. This allows users to prove their Roblox identity and receive a JWT session token.Game integration is required for self-hosting. Without it, users cannot log in.
How Verification Works
The verification flow involves multiple components:Desktop app begins verification
User clicks login. Desktop calls
auth.beginVerification and receives:sessionId: UUID for pollingcode: 6-digit verification code (e.g., “123456”)placeId: Where to verifyexpiresAt: Expiration timestamp (10 minutes)
User joins verification place
Desktop displays the code and directs user to join the Roblox place at
placeId.Game calls completeVerification
When user joins, the Roblox game server script:
- Gets the verification code from the user (via GUI or chat)
- Calls
auth.completeVerificationendpoint with:code: Verification coderobloxUserId: User’s Roblox IDx-verification-secret: Shared secret header
Backend validates and completes
Backend:
- Validates
x-verification-secretheader - Checks if code exists and hasn’t expired
- Fetches Roblox user profile
- Creates JWT session
- Marks verification as complete
Backend API Endpoints
Your Roblox game interacts with these tRPC endpoints.Complete Verification Endpoint
Procedure:auth.completeVerificationType: Mutation (HTTP POST)
Middleware:
gameVerificationProcedure (requires x-verification-secret header)
Input Schema:
UNAUTHORIZED: Invalid or missing verification secretBAD_REQUEST: Invalid/expired codeTOO_MANY_REQUESTS: Rate limit exceeded (20 requests per minute per user)
packages/api/src/routers/auth.ts:102-152
Verification Secret Validation
The backend validates the secret using timing-safe comparison:packages/api/src/trpc.ts
Roblox Game Integration
Implement server-side verification in your Roblox game.Prerequisites
Enable HTTP requests
In Roblox Studio:
- Home → Game Settings → Security
- Enable “Allow HTTP Requests”
- Save and publish
Configure verification place
Set
VERIFICATION_PLACE_ID in backend .env to your place ID:apps/server/.env
Server Script Implementation
Create a server script (ServerScriptService) to handle verification:ServerScriptService/BloxChatVerification
Client GUI (Optional)
Create a simple GUI for users to enter their verification code:StarterGui/VerificationGui/LocalScript
Alternative: Chat Command
Allow users to verify via chat command:ServerScriptService/ChatCommands
Security Best Practices
Never expose VERIFICATION_SECRET to clients
Store the secret only in server scripts. Never:
- Send to client via RemoteEvent/RemoteFunction
- Store in ReplicatedStorage or client-accessible locations
- Log or print in game output
Rate limit verification attempts
The backend has built-in rate limiting (20 requests/minute per user), but you can add additional client-side checks:
Use HTTPS in production
Always use HTTPS for your API URL:HTTP connections expose the verification secret in transit.
Testing the Integration
Publish your Roblox game
- Add the server script to ServerScriptService
- Set
VERIFICATION_SECRETin the script - Publish to Roblox
Test the flow
- Launch BloxChat desktop app
- Set API URL to your backend (Settings)
- Click “Login”
- Note the verification code
- Join your Roblox verification place
- Enter code via GUI or chat command
- Desktop app should complete login
Troubleshooting
401 Unauthorized - Invalid verification secret
401 Unauthorized - Invalid verification secret
400 Bad Request - Invalid or expired code
400 Bad Request - Invalid or expired code
The verification code is incorrect or has expired.Checks:
- Code expires after 10 minutes
- Code can only be used once
- Ensure code is typed correctly (case-sensitive)
- Desktop app must call
beginVerificationfirst
429 Too Many Requests - Rate limit
429 Too Many Requests - Rate limit
Too many verification attempts from this user.Backend limits:
- 20 requests per minute per
robloxUserId
HTTP requests fail in Roblox
HTTP requests fail in Roblox
Enable HTTP requests:
- Roblox Studio → Home → Game Settings
- Security tab
- Enable “Allow HTTP Requests”
- Save and republish
- Verify URL is correct (include
https://) - Test in browser:
https://your-api-domain.com/ - Check firewall/network settings
Desktop app stuck on 'Waiting for verification'
Desktop app stuck on 'Waiting for verification'
The game never called
completeVerification, or it failed.Debug steps:- Check Roblox Output window for errors
- Verify server script is in ServerScriptService
- Ensure RemoteEvent wiring is correct
- Check backend logs for incoming requests
- Verify
VERIFICATION_PLACE_IDmatches your place
CORS errors (browser-based testing)
CORS errors (browser-based testing)
The backend uses CORS middleware to allow all origins:If you need to restrict origins, modify the
apps/server/src/index.ts
cors() call.Advanced: Custom Verification Flow
You can customize the verification flow for your needs.Store Verification Codes in DataStore
Persist codes across server shutdowns:Auto-verify on join
If you store codes in advance:Multi-place support
If users can verify in multiple places:Next Steps
Environment Variables
Review all backend configuration options
Server Setup
Deploy and manage your backend server