Authentication

Authenticating With playPORTAL
Reminder: if you are using an app/client ID in sandbox, you must use sandbox.playportal.io as the endpoint for your requests.  Requests to api.playportal.io with a sandbox client ID will fail!
To authenticate a playPORTAL user in a 3rd party app, you will need to follow the playPORTAL OAuth flow.  Before beginning this process, you will need to have an app created with a client ID and secret, as well as a registered redirect UI in playPORTAL Studio.
Authorization Request
First, display a playPORTAL auth screen to the user.  Use your client ID identify your application to the user and enter the URI you wish the auth screen to redirect the user to upon auth completion.
GET https://api.playportal.io/oauth/signin?response_type=code
&client_id=<CLIENT_ID>
&redirect_uri=<REDIRECT_URI>
&state=NONCE
state: a string value provided by the web server application that maintains state between the authorization request and the playPORTAL server response. The value will be returned as a request parameter to the redirect URI and should be validated by the web server. This may be a nonce or base64 encoded object with information relevant for the web server application.
Authorization Prompt
In response to the authorization request, a web page login form for playPORTAL is displayed. The user logs in and decides whether or not to allow to your app. After the user decides, playPORTAL will redirect to the redirect URI provided in the initial request.
GET <REDIRECT_URI>?code=AUTH_CODE&state=NONCE
In the case of a failed login or denial of permissions, an error is returned:
GET <REDIRECT_URI>?error="User cancelled request."
Your application should be configured to handle these parameters.
Token Request
Next, your application should use the AUTH_CODE from the redirect above to generate an auth token to use with the playPORTAL API.
POST https://api.playportal.io/oauth/token?grant_type=authorization_code
    &code=<AUTH_CODE>
    &redirect_uri=<REDIRECT_URI>
    &client_id=<CLIENT_ID>
    &client_secret=<CLIENT_SECRET>
You will need your Client Secret in addition to your client ID in this step.
The response from playPORTAL will be:
{
    "access_token": "<ACCESS_TOKEN>",
    "refresh_token": "<REFRESH_TOKEN>",
    "expires_in": "1d",
    "token_type": "Bearer"
}
access_token - the playPORTAL access token to use in API calls. Use this token in the "Authorization" header as follows: Authorization: Bearer <ACCESS_TOKEN> .  The access token uniquely identifies the logged in user and your app on the playPORTAL platform.
refresh_token - once the access token expires, the web server application can retrieve a new one with the refresh token (see below).
expires_in - length of life for the access token before it must be refreshed.
After this step is complete, the user is officially logged into the playPORTAL platform and can use the API as normal using their access token.
Refreshing an Access Token
When the access token expires (defined by the expires_in field), it must be refreshed for the user to continue to use the API.
Make a call to the token URL to refresh an access token:
POST https://api.playportal.io/oauth/token?grant_type=refresh_token
    &refresh_token=<REFRESH_TOKEN>
    &client_id=<CLIENT_ID>
    &client_secret=<CLIENT_SECRET>
This is only request that requires a refresh token.  All other requests should only include the access token in the Authorization header unless otherwise specified by the API docs.
A refresh token uniquely identifies a session and a device for a user.
When to Refresh a Token
For security reasons, the playPORTAL API uses a relatively short access token life of 24 hours.  Since access tokens only a short period of time, your app will need to refresh them to maintain usability.  There are generally two strategies for determining when to refresh a token.
Refresh Based on Time
With this strategy, your app will need to keep track of when the access token was generated, and perform a refresh before this timer expires.  This is the preferred method, as it reduces the chances of retry errors.
Refresh on Auth Failure
Alternately, apps can automatically refresh an access token when the API indicates that the token has expired.  The API will return the following when a client attempts to use an expired token:
401: Unauthorized
body: {
    "error_description": "Token refresh required",
    "error_code": 4010
}
The "error_description" and "error_code" are also included in response headers if the response body is unavailable.
 At this point, the client should pause its request, refresh the access token, and then retry with the refreshed access token.
Make sure you pause or queue all other requests until the refresh is complete!
Last modified 3yr ago