Meta Developers

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 Quest 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 Quest 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 Quest 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:

Parameter	Param Type	Description	Type
`access_token`	Header	Required. A bearer token that contains one of the following: App credentials - the app ID and app secret separated by the pipe symbol User credentials - the user access token Use the app credentials when making a request on behalf of the server, and the user credentials when you make a request on behalf of the user client.	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: Specifying a a non-empty value for a locale that doesn't exist in the map results in that locale being added. Specifying a non-empty value for a locale that exists in the current map results in that locale being updated with the new value. Specifying an empty string for a locale that exists in the current map results in that locale being deleted. Specifying an empty string for a locale that doesn't exist in the current map has no affect on the map. If a locale already exists in the map, you must explicitly specify it with a different value or an empty string for the value to change.	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"}

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:

Parameter	Param Type	Description	Type
`access_token`	Header	Required. A bearer token that contains one of the following: App credentials - the app ID and app secret separated by the pipe symbol User credentials - the user access token Use the app credentials when making a request on behalf of the server, and the user credentials when you make a request on behalf of the user client.	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.

{"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:

Parameter	Param Type	Description	Type
`access_token`	Header	Required. A bearer token that contains one of the following: App credentials - the app ID and app secret separated by the pipe symbol User credentials - the user access token Use the app credentials when making a request on behalf of the server, and the user credentials when you make a request on behalf of the user client.	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 - `sort_order` `entry_write_policy` `entry_count` `destination`	A comma-separated list of strings

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:

Parameter	Param Type	Description	Type
`access_token`	Header	Required. A bearer token that contains one of the following: App credentials - the app ID and app secret separated by the pipe symbol User credentials - the user access token Use the app credentials when making a request on behalf of the server, and the user credentials when you make a request on behalf of the user client.	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 - `user {id, alias, profile_url}`. Gets the id, profile name, and profile picture URL for the user. `rank` - The entry's rank relative to the current filter. The top entry on the leaderboard has a rank of one `score` - the entry's score. `display_score` - the integer representing score that will be displayed to users. `timestamp` - Unix time for when the entry was posted. `destination` - The destination associated with a leaderboard. Can retrieve values `api_name`, `display_name`, and `deeplink_message` for a given destination. `extra_data_base64` - The entry's app-supplied metadata, base64 encoded.	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 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:

Parameter	Param Type	Description	Type
`access_token`	Header	Required. A bearer token that contains one of the following: App credentials - the app ID and app secret separated by the pipe symbol User credentials - the user access token Use the app credentials when making a request on behalf of the server, and the user credentials when you make a request on behalf of the user client.	string

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:

Parameter	Param Type	Description	Type
`access_token`	Header	Required. A bearer token that contains one of the following: App credentials - the app ID and app secret separated by the pipe symbol User credentials - the user access token Use the app credentials when making a request on behalf of the server, and the user credentials when you make a request on behalf of the user client.	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 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:

Parameter	Param Type	Description	Type
`access_token`	Header	Required. A bearer token that contains one of the following: App credentials - the app ID and app secret separated by the pipe symbol User credentials - the user access token Use the app credentials when making a request on behalf of the server, and the user credentials when you make a request on behalf of the user client.	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

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:

Parameter	Param Type	Description	Type
`access_token`	Header	Required. A bearer token that contains one of the following: App credentials - the app ID and app secret separated by the pipe symbol User credentials - the user access token Use the app credentials when making a request on behalf of the server, and the user credentials when you make a request on behalf of the user client.	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}

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?