Meta Developers

Due to the scheduled deprecation of the Scoreboard app on December 20th, 2024, the Challenges API is currently unsupported. We currently do not recommend implementing the Challenges API into your app, pending future updates.

Server to Server APIs

The server-to-server (S2S) Rest APIs provide a secure channel to interact with Meta Horizon platform services. For example, you might want to update a Meta Quest Challenge’s visibility from private to public. This topic provides details about the Meta Quest Challenge 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.

Note: Older versions of Unity using .NET 3.5 or earlier don’t support SSL certificates that use SHA2 and can’t be used for server-to-server requests.

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 Users.GetAccessToken() method.

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.

Create a Challenge

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

Method: POST

Example Request:

POST /1234757621998335/challenges/?api_name=leaderboard_api_name=hello_friends&creation_type=DEVELOPER_CREATED&visibility=PRIVATE&title=sample_challenge
Host: graph.oculus.com
Authorization: Bearer OC|1234f7a788b0c0b270f9691d0a06d5a5

Example cURL Request:

curl -X POST https://graph.oculus.com/$APP_ID/challenges -d "access_token=OC|$APP_ID|$APP_SECRET" -d "leaderboard_api_name=sample_leaderboard" -d "creation_type=DEVELOPER_CREATED" -d "visibility=PRIVATE" -d "title=sample_challenge"

Parameter	Param type	Description	Type
`leaderboard_api_name`	Query	Required. The unique API name for the leaderboard associated with your challenge.	string
`creation_type`	Query	Required. Should always be “DEVELOPER_CREATED” using this method.	Enum, value `DEVELOPER_CREATED`
`visibility`	Query	Required. Either `PUBLIC`, `INVITE_ONLY`, or `PRIVATE`. `PUBLIC`: Any user can see the challenge, and can join even without an invite. `INVITE_ONLY`: Any user can see the challenge, but only those with an invite can join it. This is intended to be used for e.g. challenges with special limited participants, but when you still want to publicize the challenge so others can observe. `PRIVATE`: Only those with an invite can see the challenge or join it.	Enum, value `PUBLIC`, `INVITE_ONLY`, or `PRIVATE`
`title`	Query	The title of the challenge.	string
`description`	Query	A description of the challenge.	string
`start_date`	Query	Start date of the challenge.	date
`end_date`	Query	End date of the challenge. Defaults to three days later.	date
`fields`	Query	A comma separated list of fields to retrieve. Possible values - `id` `title` `description` `start_date` `end_date` `leaderboard` `creation_type` `visibility` `entries` `invited_users` `participants`	A comma-separated list of strings

Example response:

{
	"id": "2643098232993236",
	"title": "hello_challenge",
	"start_date": "2020-07-14T22:58:24+0000",
	"end_date": "2020-07-17T22:58:24+0000",
	"leaderboard": {
		"id": "3123283331082599"
	}
}

Change a challenge’s visibility, start or end date

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

Method: POST

Example Request:

POST /1234757621998335?visibility=INVITE_ONLY
Host: graph.oculus.com
Authorization: Bearer OC|1234f7a788b0c0b270f9691d0a06d5a5

Example cURL Request:

curl -X POST https://graph.oculus.com/$CHALLENGE_ID -d "access_token=OC|$APP_ID|$APP_SECRET" -d "visibility=INVITE_ONLY"

Parameter	Param type	Description	Type
`visibility`	Query	Either `PUBLIC`, `INVITE_ONLY`, or `PRIVATE`. `PUBLIC`: Any user can see the challenge, and can join even without an invite. `INVITE_ONLY`: Any user can see the challenge, but only those with an invite can join it. This is intended to be used for e.g. challenges with special limited participants, but when you still want to publicize the challenge so others can observe. `PRIVATE`: Only those with an invite can see the challenge or join it. This is generally only for user-created challenges among friends, not developer-created challenges.	Enum, value “`PUBLIC`”, “`INVITE_ONLY`”, or “`PRIVATE"`
`start_date`	Query	Date	integer that represents a Unix timestamp
`end_date`	Query	Date. This defaults to 3 hours after the start date.	integer that represents a Unix timestamp
`fields`	Query	A comma separated list of fields to retrieve. Possible values - `id` `title` `description` `start_date` `end_date` `leaderboard` `creation_type` `visibility` `entries` `invited_users` `participants`	A comma-separated list of strings

Example return:

{
	"success": true
}

Delete a challenge

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

Method: DELETE

DELETE /12347576219983357
Authorization: Bearer OC|1234f7a788b0c0b270f9691d0a06d5a5

Example cURL Request:

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

Example return:

{
	"success": true
}

Get a list of challenges in your application

Use this method to return a list of challenges in your application attached to a given leaderboard.

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

Method: GET

Example Request:

GET /1234757621998335/challenges
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

Example cURL Request:

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

Parameter	Param type	Description	Type
`leaderboard_api_name`	Query	By default will get challenges for all leaderboards. Use `leaderboard_api_name` to return challenges for a single leaderboard.	String
`include_active_challenges`	Query	Default true. If false, does not return past challenges for your application.	Boolean
`include_past_challenges`	Query	Default false. If true, returns challenges with end dates in the past.	Boolean
`include_future_challenges`	Query	Default false If true, returns challenges with start dates in the future.	Boolean
`fields`	Query	A comma separated list of fields to retrieve. Possible values - `id` `title` `description` `start_date` `end_date` `leaderboard` `creation_type` `visibility` `entries` `invited_users` `participants`	A comma-separated list of strings

Retrieve Data about a Challenge

Use this method to return information about one challenge in your application.

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

Method: GET

Example Request:

GET /1234757621998335?fields=id,title,description,start_date,end_date,leaderboard
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

Example cURL Request:

curl -G https://graph.oculus.com/$CHALLENGE_ID -d "access_token=OC|$APP_ID|$APP_SECRET" -d "fields=id,title,description,start_date,end_date,leaderboard"

Parameter	Param type	Description	Type
`fields`	Query	A comma separated list of fields to retrieve. Possible values - `id` `title` `description` `start_date` `end_date` `leaderboard` `creation_type` `visibility` `entries` `invited_users` `participants`	A comma-separated list of strings

Example response:

{
	"title": "sample_challenge",
	"description": "Let's see who can climb the highest!",
	"id" : "2643098232993236",
  "leaderboard": {
        "id": "7410520479067243"
    }
}

Get Challenge Score Entries

Use this method to return score entries for one challenge.

Method: GET

URL: https://graph.oculus.com/{challenge_id}/entries

Example Request:

GET /1234757621998335/entries
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5

Example cURL Request:

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

Parameter	Param type	Description	Type
`filter`	Query	This reduces the scope of score entries that are returned.	Enum, value `NONE`(default), `FRIENDS`, or `USER_IDS` `NONE`: No filter enabled on the leaderboard. `FRIENDS`: Filter the leaderboard to include only friends of the current user. `USER_IDS`: Filter the leaderboard to include specific user IDs. Use this filter to get rankings for users that are competing against each other
`start_at`	Query	Defines which order the entries are returned in.	Enum, value `TOP` (default), `VIEWER`, `VIEWER_OR_TOP`, or `OFFSET`
`offset`	Query	Required when the start-at value is offset and indicates the offset value to use.	Integer
`limit`	Query	Reduce the amount of entries returned to this number.	Integer
`user_ids`	Query	Return entries for a given set of users.	List of integers representing user ids.
`fields`	Query	A comma separated list of fields to retrieve. Possible values - `id` `challenge` `user` `rank` `score` `timestamp` `extra_data`	A comma separated list of strings