Some platform features use server-to-server (S2S) REST API calls to perform actions not appropriate to be sent from client devices. These APIs are provided to ensure a secure interaction between your back-end servers and the Oculus Platform.
For example, we use these APIs to make in-app purchases more secure and prevent fraud.
Details about individual S2S calls can be found using the links in the Features section.
Note: Unity editor incompatibility. Older versions of Unity use .NET 3.5 or earlier, which does not support SSL certificates that use SHA2. Modern SSL certs use SHA2 because SHA1 has been compromised. Unity clients that attempt to use the S2S APIs directly can not trust the response message because they can’t decrypt the SHA2-based SSL certs that the API uses.
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.
Following is an example server API call. This example shoes how to unlock a client-authoritative achievement that a user has earned. This example assumes that you have already created the achievement and integrated the hooks into your app, additional information can be found on the Achievements page.
ovr_User_GetLoggedInUser on Unity to retrieve the ID. It will be returned as the ovrID of the user.api_name of the achievement you wish to update or unlock from the client device to your server.12345678980142735f8730a4n51c5f8v8122aaf971b937e7You can then form the App Access Token as: OC|1234567898014273|5f8730a4n51c5f8v8122aaf971b937e7.
Call the API to unlock the achievement - Once you’ve retrieved the information from the client device and formed the App Access Token, send the API call to unlock the achievement.
$ curl -d "access_token=OC|1234567898014273|5f8730a4n51c5f8v8122aaf971b937e7" -d "api_name=MY_SIMPLE_ACHIEVEMENT" -d "force_unlock=true" https://graph.oculus.com/$USERID/achievements
The following shows the response to indicate the request was successful.
{ "id":"$USERID", "api_name":"MY_SIMPLE_ACHIEVEMENT", "just_unlocked":true }
You can then pass a message back to the client indicating that the achievement has been successfully unlocked.
Following is a list of platform solutions that provide server APIs
The Oculus S2S REST APIs support the standard HTTP status codes indicate what the issue is.
| Code | Status |
|---|---|
| 400 | Bad Request |
| 401 | Unauthorized Request |
| 403 | Forbidden Request |
| 404 | Not Found |
| 500 | Internal Server Error |