The server-to-server (S2S) Rest APIs provide a secure channel to interact with Meta Horizon platform. For example, you might want to update an Meta leaderboard after you host a multi-player match on your server. This topic provides details about the leaderboard-related server calls that you can make.

Message Basics

There are some server to server message basics you should be familiar with.

Server-to-Server API requirements

Calls to these APIs must meet the following requirements:

Endpoint

Make all server-to-server requests to this endpoint:

https://graph.oculus.com

Access token

Include an access token with every request to authenticate it either as a valid server request or on behalf of a specific user. The access token can be one of the following:

App Credentials

User Access Token

App credentials

App credentials authenticate your server’s back-end as a trusted resource. Never share these credentials with any client-side application.

The access token with app credentials includes the App ID and App Secret from the API page on the Meta Horizon Developer Dashboard. It follows this format: OC|$APPID|$APPSECRET.

If your credentials are compromised or you need new API credentials, generate a new app secret. Changing the app secret will revoke the permissions of the previous one. Accessing the app secret requires an administrator account.

User access token

A user access token authenticates requests on behalf of a user. Use this token type when actions relate to a specific user. An example case is updating a client-authoritative leaderboard with the results of a server-hosted multiplayer match. For each user, you would use the user access token to authenticate your server as you make requests to update their leaderboards.

Retrieve the user token with the ovr_User_GetAccessToken() method.

Alternatively, use the following blueprint function:

Blueprint function with User Access Tokens

The token will be returned as a response and can be passed from the client to your server.A user access token contains FRL or OC and a long alpha numeric string similar to the following: FRL12342GhFccWvUBxPMR4KXzM5s2ZCMp0mlWGq0ZBrOMXyjh4EmuAPvaXiMCAMV9okNm9DXdUA2EWNplrQ.

Additionally, you can retrieve your user token for testing purposes at the ‘User Token’ section of the API page of the Meta Horizon Developer Dashboard, which is at the left navigation bar.

App ID

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

Note: The cURL examples demonstrate calls with the Windows command line. Other platforms may vary.

Create or Update a Leaderboard

Use this method to create a leaderboard, or update the properties of an existing one. You can use this method to specify or update localized display titles for the leaderboard. See the title_locale_map parameter for more details.

Note: Leaderboard metadata can be retrieved by anyone. Avoid storing sensitive information when creating or updating leaderboards.

URL: https://graph.oculus.com/{app_id}/leaderboards

METHOD: POST

Example Request:

POST /1234757621998335/leaderboards/?api_name=best_leaderboard&sort_order=HIGHER_IS_BETTER&entry_write_policy=CLIENT_AUTHORITATIVE&title_locale_map={"en_US":"Soccer", "en_GB":"Football"}
HTTP/1.1
Host: graph.oculus.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

Example cURL Request:

curl -d "access_token=OC|$APP_ID|$APP_SECRET" -d "api_name=best_leaderboard" -d "sort_order=HIGHER_IS_BETTER" -d "title_locale_map={\"en_US\":\"Soccer\", \"en_GB\":\"Football\"}" -d "entry_write_policy=CLIENT_AUTHORITATIVE" -d "earliest_allowed_entry_time=1463875200" -d "latest_allowed_entry_time=1964480000" https://graph.oculus.com/$APP_ID/leaderboards"

Parameters:

Example Response:

{"id":"10742336355960170"}

Create or Update a Leaderboard Entry

Use this method to create an entry for a leaderboard, or update an existing one. When you call this method, you should:

Authenticate the call with the user token if the leaderboard is client authoritative, and do not provide a user ID.

Authenticate the call with the app token if the leaderboard is server authoritative. When provide the app token, you must also provide the user ID.

URL: https://graph.oculus.com/leaderboard_submit_entry

METHOD: POST

Example Request (server authoritative):


POST /leaderboard_submit_entry/?api_name=best_leaderboard&score=12345&extra_data_base64=T271bHVz&force_update=true&user_id=123402235207175
HTTP/1.1
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

Example cURL Request (client authoritative):

curl -d "access_token=<user access token>" -d "api_name=best_leaderboard" -d "score=12345" -d "extra_data_base64=T271bHVz" -d "force_update=true" https://graph.oculus.com/leaderboard_submit_entry

Parameters:

Example Response:

The response contains a status, did_update indicates whether the entry was recorded or not. Entries will not be recorded if the user already has an entry on the leaderboard, the new score is worse than the old score, and force_update is false.

{"did_update":true,"updated_challenge_ids":[],"success":true}

Retrieve Data about Leaderboards in an Application

Use this method to get the number of entries, write policy and sort order for the leaderboard.

URL: https://graph.oculus.com/{app_id}/leaderboards

METHOD: GET

Example Request:

GET /12347576219/leaderboards/?api_name=best_leaderboard
 &fields=sort_order,entry_write_policy,entry_count
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

Example cURL Request:

curl -G -d "access_token=OC|$APP_ID|$APP_SECRET" -d "fields=sort_order,entry_write_policy,entry_count" https://graph.oculus.com/$APP_ID/leaderboards

Parameters:

Example Response:

{
    "data": [
        {
          "id": "1074273245960170",
          "sort_order": "HIGHER_IS_BETTER",
          "entry_write_policy": "CLIENT_AUTHORITATIVE",
          "entry_count": 2500
        },
        {...}
    ]
}

Retrieve Leaderboard Entries

You can retrieve leaderboard entries for users including the user ID, alias and profile URL, as well as the leaderboard rank, entry count, and more. When you call this method, you should:

Authenticate the call with the user token if the start_at param is one of the VIEWER options.

Authenticate the call with the user token if the filter param is FRIENDS.

Otherwise, authenticate the call with the app token.

URL: https://graph.oculus.com/leaderboard_entries

METHOD: GET

Example Request:

GET /leaderboard_entries/?api_name=best_leaderboard&fields=user{id, alias, profile_url}, rank, score, timestamp, extra_data_base64&filter=NONE&start_at=OFFSET&offset=10&summary=true&limit=2
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

Example cURL request:

curl -G https://graph.oculus.com/leaderboard_entries -d "access_token=$ACCESS_TOKEN" -d "api_name=best_leaderboard" -d "filter=NONE" -d "start_at=OFFSET" -d "offset=0" -d "summary=true" -d "limit=2" -d "fields=user{id,alias,profile_url},rank,score,timestamp,extra_data_base64"

Parameters:

Example Response:

{
    "data": [{
        "id": "1074233745529170",
        "user": {
            "id": "865307770207175",
            "alias": "UnknownXuid",
            "profile_url": "someUrl",
            "rank": 25,
            "score": 12345,
            "timestamp": 1456523020,
            "extra_data_base64": "T2N1bHVz"
        }
    }],
    "summary": {
        "total_count": 45
    },
    "paging": {
        "next": "...",
        "previous": "..."
    }
}

The first ID returned in the response above is the entry ID, which can be referenced and used to delete the user’s leaderboard entry.

Get All Leaderboards In An Application

Get all leaderboards in your application, including those that are not public facing.

https://graph.oculus.com/{app_id}/leaderboards

METHOD: GET

Example Request:

GET /1234757621998335/leaderboards/
HTTP/1.1
Host: graph.oculus.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

Example cURL Request:

curl -G https://graph.oculus.com/$APP_ID/leaderboards -d "access_token=OC|$APP_ID|$APP_SECRET"

Parameters:

Example Response:

{"data":[{"id":"3123283331082594"},{"id":"3063603433693729"},{"id":"3076319039125567"}]}

Delete a Single User’s Leaderboard Entry

Use this method to delete a single entry by specifying the entry-id. An entry-id is returned from the Retrieve Leaderboard Entries request.

URL: https://graph.oculus.com/{entry_id}

METHOD: DELETE

Example Request:

DELETE /12345 HTTP/1.1
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

Example cURL request:

curl -X DELETE -d "access_token=OC|$APP_ID|$APP_SECRET" https://graph.oculus.com/$LEADERBOARD_ENTRY_ID

Parameters:

Example Response:

{"success":true}

Delete All Leaderboard Entries

Delete all of the entries in a leaderboard. This operation can not be reversed.

URL: https://graph.oculus.com/leaderboard_remove_all_entries

METHOD: POST

Example Request:

POST /leaderboard_remove_all_entries?api_name=MY_NEW_LEADERBOARD
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

Example cURL request:

curl -d "access_token=OC|$APP_ID|$APP_SECRET" -d "api_name=MY_NEW_LEADERBOARD" https://graph.oculus.com/leaderboard_remove_all_entries

Parameters:

Example Response:

{"success":true}

Delete a Leaderboard

Delete a leaderboard. The leaderboard-id is the ID returned from the Create or Update a Leaderboard request. Once deleted, a leaderboard entry cannot be recovered.

URL: https://graph.oculus.com/leaderboard_id

METHOD: DELETE

Example Request:

DELETE /12345567893
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

curl -X "DELETE" -d "access_token=OC|$APP_ID|$APP_SECRET" https://graph.oculus.com/12345567893

Parameters:

Example Response:

{"success":true}

Troubleshooting

What if you follow the curl request example, but the REST API does not work?

First, you want to double check if the access_token has been set correctly. In some requests it’s OC|$APP_ID|$APP_SECRET while in some requests it’s user access token.

If you use the curl command to hit the API, please make sure you use backslash to escape characters like double quote and square bracket.

If your curl command contains data field like offset or allowed time stamps, you need to make sure the values set aligned with your query. Otherwise, the result will not be returned.

Did you find this page helpful?