Remote Unlock
Remote Unlock
Comprehensive reference for the Consumer API remote unlock endpoint — scope options, Roblox MessagingService integration, the polling acknowledgment system, and error codes.
POST
Remote Unlock
The remote unlock endpoint triggers an access point to open programmatically. The unlock command is delivered to your Roblox game server through Roblox Open Cloud MessagingService.
The interactive playground above lets you test the endpoint directly. Set your API key in the X-API-Key field, fill in the request body, and click “Try it!”
Scope Behavior
Universe Scope
An unlock with"scope": "universe" broadcasts the unlock to everyone in the game instance. No specific player is targeted. The response is returned immediately since there is no polling for acknowledgment.
Player Scope
An unlock with"scope": "player" targets a specific player identified by their Roblox user ID or username.
Either
"universe" or "player". Universe unlocks for everyone; player
unlocks for a specific user.The Roblox user ID for player-scoped unlocks. Required when
scope is
"player" and robloxUsername is not provided.An alternative to
robloxUserId. The Roblox username for player-scoped
unlocks. Resolved to a numeric user ID server-side. Required when scope is
"player" and robloxUserId is not provided.For player scope, you only need to provide one of
robloxUserId or
robloxUsername. If both are provided, robloxUserId takes precedence.Unlock Time
How long the door stays unlocked, in seconds. Must be between 2 and 60. The
access point’s configuration can override this value.
| Condition | Behavior |
|---|---|
| Omitted | Defaults to 8 seconds |
| 2–60 | Custom duration |
| Outside range | Returns HTTP 400 |
| Overridden by config | Access point configuration takes precedence |
Roblox MessagingService Message Format
When a remote unlock is triggered, XCS publishes a message to the Roblox MessagingService topicxcs-unlock-{locationId}. This is the payload your game server receives:
Message schema version. Currently
1.The location that owns the access point being unlocked.
The access point being unlocked.
"universe" or "player". Matches the scope from the request.Unlock duration in seconds.
The target player’s Roblox user ID. Present only when scope is
"player".Unique identifier for this unlock request. Used for acknowledgment tracking.
Your game server must subscribe to the
xcs-unlock-{locationId} topic via
Roblox MessagingService to receive unlock commands. The {locationId} in the
topic name matches the location’s UUID in XCS.If you are using the stock XCS package in your Roblox experience, this
subscription is handled automatically.MessagingService is currently in beta — you must be enrolled in the Roblox
beta program and enable the rblx-messaging_service-transport
flag in the Experiments tab of your experience’s settings.Polling and Acknowledgment
For player-scoped unlocks, the API uses a Redis-backed polling system to confirm delivery:- XCS publishes the unlock message to Roblox MessagingService.
- XCS sets a Redis key with the
requestIdmarking the status aspending. - Your game server processes the message and acknowledges it by writing back to the status key.
- XCS polls every 250 ms for up to 5 seconds. If it detects
completed, it returns HTTP 200 withacknowledged: true. - If no acknowledgment is received within 5 seconds, XCS returns HTTP 504.
Universe-scoped unlocks are acknowledged immediately without polling because
they do not target a specific player. The response always returns
acknowledged: true.Error Codes
| Status | Error | Resolution |
|---|---|---|
| 400 | Invalid or missing scope | Ensure scope is "universe" or "player". |
| 400 | Missing robloxUserId/robloxUsername for player scope | Provide one of these fields when using "player" scope. |
| 400 | Invalid unlockTime | Must be between 2 and 60 seconds. |
| 401 | Invalid or missing API key | Check the X-API-Key header is present and valid. |
| 403 | API key not authorized for this access point | The API key’s organization does not own this access point. |
| 404 | Access point not found | Verify the access point ID in the URL. |
| 422 | Location missing Roblox Universe ID or Open Cloud API key | Configure the Roblox integration for the location in the XCS dashboard. |
| 502 | Roblox MessagingService error | Check your Open Cloud API key and Universe ID configuration. |
| 504 | Remote unlock timed out | Your game server did not acknowledge the unlock within 5 seconds. The command was still delivered to any running server instances but no confirmation was received. |

