GameBus OAuth Token Manual

This is a page for developers who wish to leverage the GameBus Open API. The page focuses on security aspects. Please contact us if you want to learn more about API functionality beyond what is documented here. The API should be accessed via  HTTPS REST calls with JSON payload and an OAuth 2 token in the Authorization header. In the following, we describe how to get a user-specific token for your app/website/device.

Section 1 describes an approach to read the token from an app-specific file on the end user’s device. Section 2 describes an approach which sends GameBus tokens directly to your server. Section 3 describes how to decrypt the token values mentioned in sections 2 and 3.

1. Reading GameBus Tokens from the end user Phone/Tablet

If you are a developer of a mobile health app (or any app that can benefit from the GameBus leaderboards) then you may want to access the GameBus API directly from the end user’s mobile device. We can make available an app-specific token on the end user’s file system. This approach only works on Android since iOS apps cannot access the full filesystem.

SDapp

For the sake of prototyping, you can rely on the following example file content:

{
 "playerId":100023,
 "token":"c7665dad-cbae-4037-a49a-c19b86fea1a0"
}

If you manage to push activity data for this test user with name “Fien”, then please send us the name of your app, an app logo as well as a short description. We will check the maturity of your integration and

  • provide a “connect” button for your app in the GameBus base app, and
  • provide you with the exact location of the GameBus token file corresponding to your app, and
  • provide you with an app key to decrypt the token value in the token file dedicated to your app (see the decryption section).

2. Receiving the GameBus Token on your API/server

If you are not providing an app on the end user’s device, we can provide from within the GameBus base app a “connect” button which will send the OAuth token to your app’s API server. The token will then be sent in encrypted form (see the decryption section). When receiving such a request call, your server is expected to provide a user login page. When users authenticate successfully to your app, then:

  1. you should store the player ID and the token for future use for that user (note that you should also store the user ID which identifies the user in your app’s database), and
  2. you should return and end user oriented page which clarifies that from now on sessions will be sent to the user’s GameBus account.

When users fail to authenticate, you may want to provide instructive feedback, also describing options to retry.

If you wish to leverage this approach then please send us:

  • end-user friendly info:
    • the name of your app/website,
    • an app logo, as well as
    • a short description, and
    • the URL of a page with further information on your app/website;
  • technical info:
    • the URL of the page where the users can connect after authenticating to your service (e.g., https://yourserver.org/connect?userid={userId}&token={gamebusToken});
    • the URL of the page to disconnect previously connected users (e.g., https://yourserver.org/disconnect?userid={userId}&token={gamebusToken});
    • the URL of the endpoint which we can call to test whether or not a specific GameBus user is connected successfully to your app/website (e.g., https://yourserver.org/status?userid={userId}&token={gamebusToken}).

Note that when you are developing an integration in between the GameBus API and a third party API then the URL for the /connect endpoint should go to that third party API first and you should specify within that URL a redirect URI pointing to your integration server. For example, the GameBus integration for http://www.moves-app.com uses for /connect a URL like:

https://api.moves-app.com/oauth/v1/authorize?response_type=code&client_id=1234&scope=activity
&redirect_uri=https://integration-server.org/api/callback/{dataProviderId}/{userId}/{gamebusToken}

In case you manage both the integration server as well as the game server/API then you don’t have to use this redirect approach. Put differently, if the developers of http://www.moves-app.com themselves would have implemented the GameBus<>Moves integration then the GameBus /connect URL could have been as simple as:

https://api.moves-app.com/api/connectToGameBus/{userId}/{gamebusToken}

Decrypting GameBus tokens

GameBus tokens are always encrypted, both when storing them on the end user’s filesystem (cf,. section 1) as well as when sending them to your app’s server (cf., section 2). Furthermore, in approach 2, the token value will be Base64-encoded (since the encryption may produce URL unsafe characters).

Therefore, in order to get access to GameBus tokens, apps/websites will always have to decode using their app-specific app key.  More specifically, tokens are encrypted by 128-bit AES/CFB8/NoPadding (see http://aesencryption.net] to test.)  Furthermore, when following the approach from section 2, implementations of the /connect, /disconnect and /status endpoints will first have to run a Base64 decoding before even trying to run the AES decoding (see https://www.base64decode.org to test).