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.
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.
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.
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.
Next, your application should use the AUTH_CODE from the redirect above to generate an auth token to use with the playPORTAL API.
The response from playPORTAL will be:
- 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.
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:
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.
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.
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:
"error_description": "Token refresh required",
At this point, the client should pause its request, refresh the access token, and then retry with the refreshed access token.