Access Token Handling

Covers the handling of tokens for authentication purposes.

The SnapOdds SDK requires a valid access token to be provided in order to communicate with the Snapscreen API, which uses the OAuth 2.0 authentication mechanism.

Our customers are provided with a Client ID and Secret which must be used to retrieve the access token from the API endpoint described below:

Grants an access token to an anonymous user.

POST https://api.us.snapscreen.com/oauth/token

Request Body

Name	Type	Description
client_id*	String	The client identifier specific to the customer.
client_secret*	String	The client secret.
grant_type*	String	The requested access grant type, should be set to "anonymous".
device_fingerprint	String	Unique device fingerprint.

200: OK An access token and it requisites.

{
  access_token: string,
  token_type: string,
  refresh_token: string,
  expires_in: number (long),
  scope: string
}

401: Unauthorized A request lacks valid authentication credentials for the requested resource.

{
  error: string,
  error_description: string
}

403: Forbidden The server refuses to authorize request.

{
  error: string,
  error_description: string
}

400: Bad Request A request is not well formatted.

{
  error: string,
  error_description: string
}

500: Internal Server Error The server encountered an unexpected condition that prevented it from fulfilling the request.

{
  error: string,
  error_description: string
}

Below is an example of the HTTP request using curl to receive an access token:

curl -d "client_id=YourClientId&client_secret=YourClientSecret&grant_type=anonymous"  https://api.us.snapscreen.com/oauth/token

Having the access token retrieval system implemented on the client side is unsafe and strongly discouraged, as credentials are available in plain text and could easily be stolen. Therefore SnapOdds recommends implementation of this logic on the server side.

For the implementation to function, a REST API endpoint must be provided from which the client can request the access token. On the server side, the access token will be fetched from the Snapscreen API, stored in the current HTTP session, and then returned to the browser.

To further improve security, we also recommend using the CSRF token technique to protect this resource. If you have other security protection mechanisms available in your Web Application, then we highly recommend using them as well.

Let us assume a REST API endpoint has been created using the path '/token'. The next required step is to direct this endpoint to the SnapOdds SDK in the form of an access token provider, which is function that when executed will return a Promise of the whole access token returned from the Snapscreen API.

Enclosed below is a snippet of a basic implementation of the access token provider.

function fetchAccessTokenFromApi() {
  return fetch('/token', { mode: 'cors', cache: 'no-cache' })
    .then((response) => response.json());
}

Note: The access token provider must return a standard Promise (not any equivalent like AngularJS $q or other custom promise libraries like Kris Kowal's Q). The SDK is built as angular element and relies on zone.js for change detection, so only browser native async methods are recognized.