Skip to main content
POST
/
api
/
consumer
/
v1
/
access-points
/
{id}
/
remote-unlock
Remote Unlock
curl --request POST \
  --url https://api.restrafes.co/api/consumer/v1/access-points/{id}/remote-unlock \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "scope": "<string>",
  "robloxUserId": "<string>",
  "robloxUsername": "<string>",
  "unlockTime": 123
}
'
import requests

url = "https://api.restrafes.co/api/consumer/v1/access-points/{id}/remote-unlock"

payload = {
"scope": "<string>",
"robloxUserId": "<string>",
"robloxUsername": "<string>",
"unlockTime": 123
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
scope: '<string>',
robloxUserId: '<string>',
robloxUsername: '<string>',
unlockTime: 123
})
};

fetch('https://api.restrafes.co/api/consumer/v1/access-points/{id}/remote-unlock', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
package main

import (
"fmt"
"strings"
"net/http"
"io"
)

func main() {

url := "https://api.restrafes.co/api/consumer/v1/access-points/{id}/remote-unlock"

payload := strings.NewReader("{\n \"scope\": \"<string>\",\n \"robloxUserId\": \"<string>\",\n \"robloxUsername\": \"<string>\",\n \"unlockTime\": 123\n}")

req, _ := http.NewRequest("POST", url, payload)

req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
{
  "v": 123,
  "locationId": {},
  "accessPointId": {},
  "scope": "<string>",
  "unlockTime": 123,
  "robloxUserId": 123,
  "requestId": {}
}
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.
scope
string
required
Either "universe" or "player". Universe unlocks for everyone; player unlocks for a specific user.
robloxUserId
string
The Roblox user ID for player-scoped unlocks. Required when scope is "player" and robloxUsername is not provided.
robloxUsername
string
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

unlockTime
integer
default:"8"
How long the door stays unlocked, in seconds. Must be between 2 and 60. The access point’s configuration can override this value.
ConditionBehavior
OmittedDefaults to 8 seconds
2–60Custom duration
Outside rangeReturns HTTP 400
Overridden by configAccess point configuration takes precedence

Roblox MessagingService Message Format

When a remote unlock is triggered, XCS publishes a message to the Roblox MessagingService topic xcs-unlock-{locationId}. This is the payload your game server receives:
{
  "v": 1,
  "locationId": "uuid-of-the-location",
  "accessPointId": "uuid-of-the-access-point",
  "scope": "player",
  "unlockTime": 8,
  "robloxUserId": 12345,
  "requestId": "uuid-unique-request-identifier"
}
v
integer
required
Message schema version. Currently 1.
locationId
string (UUID)
required
The location that owns the access point being unlocked.
accessPointId
string (UUID)
required
The access point being unlocked.
scope
string
required
"universe" or "player". Matches the scope from the request.
unlockTime
integer
required
Unlock duration in seconds.
robloxUserId
integer
The target player’s Roblox user ID. Present only when scope is "player".
requestId
string (UUID)
required
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:
  1. XCS publishes the unlock message to Roblox MessagingService.
  2. XCS sets a Redis key with the requestId marking the status as pending.
  3. Your game server processes the message and acknowledges it by writing back to the status key.
  4. XCS polls every 250 ms for up to 5 seconds. If it detects completed, it returns HTTP 200 with acknowledged: true.
  5. 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

StatusErrorResolution
400Invalid or missing scopeEnsure scope is "universe" or "player".
400Missing robloxUserId/robloxUsername for player scopeProvide one of these fields when using "player" scope.
400Invalid unlockTimeMust be between 2 and 60 seconds.
401Invalid or missing API keyCheck the X-API-Key header is present and valid.
403API key not authorized for this access pointThe API key’s organization does not own this access point.
404Access point not foundVerify the access point ID in the URL.
422Location missing Roblox Universe ID or Open Cloud API keyConfigure the Roblox integration for the location in the XCS dashboard.
502Roblox MessagingService errorCheck your Open Cloud API key and Universe ID configuration.
504Remote unlock timed outYour 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.