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.
There are some server to server message basics you should be familiar with.
All server-to-server requests are made to the following endpoint:
https://graph.oculus.com
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 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.
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.
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.
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:
Parameter | Param Type | Description | Type |
---|---|---|---|
access_token | Header | Required. A bearer token that contains one of the following:
| string |
app_id | Path | Required. Oculus app identifier found on the API page. | integer |
api_name | Query | The unique API Name for the leaderboard. This is specified when you created the leaderboard. | string |
earliest_allowed_entry_time | Query | Optional. Enables leaderboards to have a time limit with a specific start time. If used, entries can only be posted after this time. | integer that represents a Unix timestamp |
entry_write_policy | Query | Required. Describes who is allowed to write entries - a client or the server. | Enum, valid values are: "CLIENT_AUTHORITATIVE", "SERVER_AUTHORITATIVE" |
latest_allowed_entry_time | Query | Optional. Enables leaderboards to have a time limit with a specific end time. If used, entries can only be posted before this time. | integer that represents a Unix timestamp |
sort_order | Query | Required. Describes the preferred method to sort the leaderboard; either by high or low score. | Enum, valid vales are: "HIGHER_IS_BETTER", "LOWER_IS_BETTER" |
title_locale_map | Query | Optional. JSON encoded map that specifies a locale as the key and the localized title as the value for that locale, or empty string ("") to clear the value. The locale should be formatted as an ISO-639 language code followed by the 2-letter ISO-3166 country code. example: {"en-US":"Soccer", "en-GB":"Football"} Note that:
| JSON-encoded string |
is_public | Query | Optional. Indicates if the leaderboard is publicly visible. | boolean |
destination_api_name | Query | Optional. The api name of a destination to associate with this leaderboard. | string |
score_type | Query | The score integer will be displayed based on this Enum value. The default is POINT. | Enum, valid values are: "DISTANCE_IN_FOOT", "DISTANCE_IN_METERS", "PERCENTAGE", "POINT", "TIME_IN_MILLISECOND", "TIME_IN_SECOND" |
Example Response:
{"id":"10742336355960170"}
Use this method to create an entry for a leaderboard, or update an existing one. When you call this method, you should:
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:
Parameter | Param Type | Description | Type |
---|---|---|---|
access_token | Header | Required. A bearer token that contains one of the following:
| string |
api_name | Query | The unique API Name for the leaderboard. This is specified when you created the leaderboard. | string |
score | Query | Required. The leaderboard value or score being submitted. | integer |
extra_data_base64 | Query | Optional. Extra metadata to store with the leaderboard entry. This can be used to specify information about the score. For example, in a driving game this may be what car was used. Decoded length can be, at most, 2048 bytes. | string |
user_id | Query | Required if you use the app access token to authenticate to the API. Indicate which user you are posting on behalf of. That user must have an entitlement to your app. When using a User Access Token, this field must not be set. | string |
display_score | Query | The formatted score that will be displayed in the leaderboard. | string |
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}
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:
Parameter | Param Type | Description | Type |
---|---|---|---|
access_token | Header | Required. A bearer token that contains one of the following:
| string |
api_name | Query | The unique API Name for the leaderboard. This is specified when you created the leaderboard. | string |
fields | Query | Required. A comma separated list of fields to retrieve. Possible values -
| A comma-separated list of strings |
Example Response:
{ "data": [{ "id": "1074273245960170", "sort_order": "HIGHER_IS_BETTER", "entry_write_policy": "CLIENT_AUTHORITATIVE", "entry_count": 2500 }] }
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:
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:
Parameter | Param Type | Description | Type |
---|---|---|---|
access_token | Header | Required. A bearer token that contains one of the following:
| string |
api_name | Query | The unique API Name for the leaderboard. This is specified when you created the leaderboard. | string |
fields | Query | Required. A comma separated list of fields to retrieve. Possible values -
| A comma-separated list of strings |
filter | Query | Optional. Indicates what type of filtering should be applied. | Enum value. Valid values: FRIENDS, USER_IDS, NONE |
start_at | Query | Optional. Indicates the leaderboard position to start the retrieval. | Enum value. Valid values: CENTERED_ON_VIEWER, CENTERED_ON_VIEWER_OR_TOP, TOP, OFFSET |
offset | Query | Required when the start-at value is offset and indicates the offset value to use. | integer |
summary | Query | Optional. True to indicate a summary should be provided, otherwise false. | Boolean |
limit | Query | Optional. Indicates the number limit of entries to return. | integer |
user_ids | Query | Required when the filter value is USER_IDS. Specifies which users' entries to fetch. | A comma-separated list of integers |
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 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:
Parameter | Param Type | Description | Type |
---|---|---|---|
access_token | Header | Required. A bearer token that contains one of the following:
| string |
Example Response:
{"data":[{"id":"3123283331082594"},{"id":"3063603433693729"},{"id":"3076319039125567"}]}
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:
Parameter | Param Type | Description | Type |
---|---|---|---|
access_token | Header | Required. A bearer token that contains one of the following:
| string |
entry_id | Path | Required. Identifier for a particular entry in the leaderboard. You must retrieve this with a call to get all leaderboard entries. | string |
Example Response:
{"success":true}
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:
Parameter | Param Type | Description | Type |
---|---|---|---|
access_token | Header | Required. A bearer token that contains one of the following:
| string |
api_name | Query | The unique API Name for the leaderboard. This is specified when you created the leaderboard. | string |
Example Response:
{"success":true}
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:
Parameter | Param Type | Description | Type |
---|---|---|---|
access_token | Header | Required. A bearer token that contains one of the following:
| string |
leaderboard-id | Path | Required. Numeric identifier for a leaderboard. You must retrieve this with a call to create or update a leaderboard. | string |
Example Response:
{"success":true}