Server APIs for Moderated Rooms

Moderated rooms are created through S2S REST calls. A client app should not create or maintain moderated rooms. Only your trusted servers can create or make changes to moderated rooms.

Note: The server APIs in this topic are for creating system-moderated rooms. For user-created rooms, see User-Owned Private Rooms in the Rooms topic.

Message Basics

Server-to-Server Endpoint

All server-to-server requests are made to the following endpoint:

Access Token

An access token is sent with every message and either authenticates the request as a valid server request or as a request on behalf a particular user. The access token can contain one of the following:

App Credentials

App credentials verify your server back-end as a trusted resource. These credentials should never be shared with a client-side app.

An access token with app credentials contains the App ID and App Secret from the API page in the Developer Dashboard in the following format: OC|$APPID|$APPSECRET.

You can generate a new app secret if your credentials are compromised or you need a fresh set of API credentials. If you change the app secret, the permissions of the previous app secret are revoked. Note that you must use an admin account to access the app secret from the API page.

Note: Older versions of Unity use .NET 3.5 or earlier, which does not support SSL certificates that use SHA2 and cannot be used for server-to-server requests.

User Access Token

A user access token verifies a request on behalf of a user is valid. Use a user access token when interacting on behalf of a user, or in reference to a specific user. For example, after a server-hosted multiplayer match may want to update a client-authoritative leaderboard with the results of the match. In this scenario, your server would make a call to update the leaderboard entry for each user with the results of the match using the user access token to identify the user.

Retrieve the user token with the ovr_User_GetAccessToken() method.

The token will be returned as a response and can be passed from the client to your server. An access token with a user credentials contains OC and a long alpha numeric string similar to the following: OC12342GhFccWvUBxPMR4KXzM5s2ZCMp0mlWGq0ZBrOMXyjh4EmuAPvaXiMCAMV9okNm9DXdUA2EWNplrQ.

Additionally, you can retrieve your user token for testing purposes at the bottom of the API page in the Developer Dashboard.

App ID

Some server calls require an app ID, which you can find on the API page in the Developer Dashboard.

Create a Moderated Room

Calling this endpoint will create a new moderated room.



Example cURL Request:

$ curl -d 'access_token=$APP_ACCESSTOKEN'  -d 'max_users=MY_MAX_USER_COUNT'

You’ll need to include the max_users parameter which identifies the max simultaneous users for the room. The maximum number of users supported per room is 1,024.

Example response:

{"id": 963119010431337}

In response the API will return the moderated_room_id as the id value. Call this id when adding users to the room.

Update a Moderated Room’s Metadata

Calling this endpoint sets up to 2,000 key/value pairs in the room datastore. Key and value data can only be accepted as string values, any other value type will return an error. The ROOM_ID is the value returned from the API when you created the room.



Example cURL Request:

$ curl -d 'access_token=$APP_ACCESSTOKEN' -d 'room_id=$ROOM_ID'
-d 'data_store=[{"key":"KEY","value":"VALUE"},{"key":"KEY2","value":"VALUE2"}]'

Example response:

{"success": true}

Retrieve Information about a Moderated Room

Calling this endpoint will retrieve information about a specified moderated room. The ROOM_ID is the value returned from the API when you created the room. The parameters in the example below are all optional, information will only be returned for the parameters identified in the request.



Example cURL Request:

$ curl -G -d 'access_token=$APP_ACCESSTOKEN' -d 'fields=max_users,owner{id,alias,presence,presence_status,profile_url,profile_url_small},

Delete a Moderated Room

Calling this endpoint will delete a moderated room.



Example cURL Request:


Example response:

{"success": true}

Join Users to System-Moderated Rooms

Once system-moderated rooms are created, you use client APIs so that users can find, join and leave rooms. For a list of these APIs, see Get, Join and Leave Rooms in the Rooms topic.