Leaderboards Server APIs

The server-to-server (S2S) Rest APIs provide a secure channel to interact with Oculus platform services. For example, you might want to update an Oculus leaderboard after you host a multi-player match on your server. This topic provides details about the Oculus 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 Endpoint

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

https://graph.oculus.com

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
• User Access Token

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.

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.

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|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a" ^
-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=1464480000" ^
https://graph.oculus.com/12347576219/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=OC1234OYRxTfgiFehJN4PrZBx4PH1D5SfGWn7z1ix06dpsZAhHPhN9z1F" ^
-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.

{"success": true,
"did_update": true}

Retrieve Data about a Leaderboard

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=OC1234f7a788b0c0b270f9691d0a06d5a5" ^
-d "fields=sort_order,entry_write_policy,entry_count" ^
https://graph.oculus.com/12347576219/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 -d "access_token=OC1234OYRxTfgiFehJN4PrZBx4PH1D5SfGWn7z1ix06dpsZAhHPhN9z1F" ^
-d "api_name=best_leaderboard" ^
-d "filter=NONE" -d "start_at=OFFSET" -d "offset=10" -d "summary=true" ^
-d "limit=2" ^
-d "fields=user{id,alias,profile_url},rank,score,timestamp,extra_data_base64" ^
https://graph.oculus.com/leaderboard_entries

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 -d "access_token=OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a" https://graph.oculus.com/2963766027051815/leaderboards

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 Data about a User’s Leaderboard Entry 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 "OC1234757621998335f7a788b0c0b270f9691d0a06d5a5" ^
https://graph.oculus.com/12345

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 "OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5" ^
-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|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5" ^
https://graph.oculus.com/12345567893

Parameters:

Example Response:

{"success":true}