Challenges Server to Server APIs

Challenges Availability

Challenges are not open to all developers at this time. Please contact the Facebook Reality Labs Developer Relations contact to access this feature.

Server to 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 Challenge’s visibility from private to public. This topic provides details about the Oculus 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 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

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.

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/1234757621998335/challenges -d "OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5"-d "leaderboard_api_name=sample_leaderboard" -d "creation_type=DEVELOPER_CREATED" -d "visibility=PRIVATE" -d "title=sample_challenge"
ParameterParam typeDescriptionType
leaderboard_api_nameQuery Required. The unique API name for the leaderboard associated with your challenge. string
creation_typeQuery Required. Should always be “DEVELOPER_CREATED” using this method. Enum, value DEVELOPER_CREATED
visibilityQuery 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
titleQuery The title of the challenge. string
descriptionQuery A description of the challenge. string
start_dateQuery Start date of the challenge. date
end_dateQuery End date of the challenge. Defaults to three days later. date
fieldsQueryA 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/1234757621998335 -d "OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5"-d "visibility=INVITE_ONLY"
ParameterParam type Description Type
visibilityQuery 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_dateQuery Date integer that represents a Unix timestamp
end_dateQuery Date. This defaults to 3 hours after the start date. integer that represents a Unix timestamp
fieldsQuery 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/1234757621998335 -d "OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5"

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/1234757621998335/challenges -d "OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5"
Parameter Param type Description Type
leaderboard_api_nameQuery By default will get challenges for all leaderboards. Use leaderboard_api_name to return challenges for a single leaderboard. String
include_active_challengesQuery Default true. If false, does not return past challenges for your application. Boolean
include_past_challengesQuery Default false. If true, returns challenges with end dates in the past. Boolean
include_future_challengesQuery Default false If true, returns challenges with start dates in the future. Boolean
fieldsQuery 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/1234757621998335 -d "OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5" -d "fields=id,title,description,start_date,end_date,leaderboard"
Parameter Param type Description Type
fieldsQuery 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"
}

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/1234757621998335/entries -d "OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5"
Parameter Param type Description Type
filterQuery This reduces the scope of score entries that are returned. Enum, value NONE(default), FRIENDS, or USER_IDS
start_atQuery Defines which order the entries are returned in. Enum, value TOP (default), VIEWER, VIEWER_OR_TOP, or OFFSET
offsetQuery Required when the start-at value is offset and indicates the offset value to use. Integer
limitQuery Reduce the amount of entries returned to this number. Integer
user_idsQuery Return entries for a given set of users. List of integers representing user ids.
fieldsQuery A comma separated list of fields to retrieve. Possible values -
  • id
  • challenge
  • user
  • rank
  • score
  • timestamp
  • extra_data
A comma separated list of strings