Challenges Server to Server APIs

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
• 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.

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"

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"

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"

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"

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"