Server-to-Server API Basics

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.

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.

Example Server Call

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.

  1. Retrieve the user’s id - To call the Oculus APIs on behalf of a user you need to include the Oculus Id identifying that user. Call ovr_User_GetLoggedInUser on Native or Platform.Users.GetLoggedInUser on Unity to retrieve the ID. It will be returned as the ovrID of the user.
  2. Pass the information to your trusted server - Once you’ve retrieved the Oculus ID, pass the ID and the api_name of the achievement you wish to update or unlock from the client device to your server.
  3. Form the App Access Token - Use the following credentials that we retrieved from the API section of the Developer Center:
    • App Id - 1234567898014273
    • App Secret - 5f8730a4n51c5f8v8122aaf971b937e7

You can then form the App Access Token as: OC|1234567898014273|5f8730a4n51c5f8v8122aaf971b937e7.

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

Features with Server APIs

Following is a list of platform solutions that provide server APIs

Error Responses and HTTP Codes

The Oculus S2S REST APIs support the standard HTTP status codes indicate what the issue is.

CodeStatus
400Bad Request
401Unauthorized Request
403Forbidden Request
404Not Found
500Internal Server Error