Overview

External web sites and mobile applications use "Authorization Code Grant" authorization workflow. You can get detailed authorization process description at "4.1. Authorization Code Grant". To get authorized, application generates authorization URL and opens it in browser, user enters credentials and authorize your application. In case of successful authorization, your application receives one-time authorization code via callback URL. Access code should be exchanged to pair access and refresh tokens. For all further requests application can get new access token based on refresh token.

Callback URL

The Trakopolis API server requires you to have a callback URL (also known as redirect url) to follow OAuth2 authorization workflow. After successful authorization user is redirected back to your website or mobile application. The Trakopolis API server adds to callback URL an extra query string parameter that contains authorization code.

For web applications, you should have an endpoint at your server that accepts callback and finishes authorization. It is highly recommended to use HTTPS-based endpoint to improve security and prevent possibility of access code theft.

For mobile applications callback URL is used to detect moment in time when Trakopolis website finished authorization and redirected back to your application, so you can read an access code from query parameters. The most reliable way would be to use special scheme like myapp://callback or just plain HTTPS pointing to non-existent local resource like https://localhost:12345. If your platform doesn’t support custom schemes or non-existing localhost endpoints, then you can use link to empty page at the Trakopolis API server https://api.trakopolis.com/mobilecallback but please take into account that it can slow down authorization process because of extra request sent to our server. 

Initial OAuth2 authorization (get refresh and access tokens)

In the examples below it is assumed, that your application has these credentials:

  • ClientId = YourClientId==
  • ClientSecret = YourClientSecret
  • Callback URL = https://yourwebsite.com/AuthorizeCallbackUrl

Authorization process description:

1. A call is initiated from browser by navigating page /api/oauth2/authorize to request for an access code. Client identifier, client secret, callback URL and state are passed with this request as query string parameters. Mobile apps should host browser control within an application or invoke external browser. User enters username and password on Trakopolis website. URL example:

https://api.trakopolis.com/api/oauth2/authorize?response_type=code&client_id=YourClientId%3d%3d&redirect_uri=https%3a%2f%2fyourwebsite.com%2fAuthorizeCallbackUrl&state=YourStateValue

Please note, that all values must be URL encoded. "=" character is encoded as "%3d" etc. It is recommended to use state - an opaque value unique for every request, used by your application to maintain state between the request and callback.  The Trakopolis API server includes this value when redirecting back to your application.

2. Trakopolis OAuth2 authorization server processes request and shows user authorization form in browser, where user can allow or deny an access to your application. If authorization request is malformed or callback URL is invalid, Trakopolis website shows an error message and stops authorization process at this point.

3. If user authorized your application, the Trakopolis API server issues an access code and returns it to caller. If user denied access or any error occurs, the Trakopolis website redirects user browser back to your website (or mobile application). The Trakopolis API server uses callback URL to return user back to your webiste or mobile application. Please note that you may get URL Encoded characters in code. For example, %21 as in example below. You must decode this to get real value of code (OSsN%21IA... => OSsN!IA...).

  • Successful authorization example: https://yourwebsite.com/AuthorizeCallbackUrl?code=OSsN%21IAAAADyk79aTAnKl3gnSnogpsa2yVEt3PmxZ0UZFhidH5Vhz8QAAAAFAnNPWZpBM7D8tRoNHoSEUOit-IaLBWeg&state=YourStateValue
  • Error authorization example: https://yourwebsite.com/AuthorizeCallbackUrl?error=access_denied&state=YourStateValue 

4. After your website or mobile application received an authorization code, the code should be exchanged to pair of access and refresh tokens. A call is made for an access token /api/oauth2/token and authorization code is passed.

  • Request URL: https://api.trakopolis.com/api/oauth2/token
  • Request Method: POST
  • Content-Type: application/x-www-form-urlencoded
  • Authorization: Basic WW91ckNsaWVudElkPT06WW91ckNsaWVudFNlY3JldA==
  • POST Data: grant_type=authorization_code&code=OSsN!IAAAADyk79aTAnKl3gnSnogpsa2yVEt3PmxZ0UZFhidH5Vhz8QAAAAFAnNPWZpBM7D8tRoNHoSEUOit-IaLBWeg&redirect_uri=https%3a%2f%2fyourwebsite.com%2fAuthorizeCallbackUrl

To receive HTTP Basic authorization, your application should combine the ClientId and ClientSecret, separated by a single colon (":") character, and then perform base64 encoding.  For example, YourClientId==:YourClientSecret represented as WW91ckNsaWVudElkPT06WW91ckNsaWVudFNlY3JldA==

The Trakopolis OAuth2 authorization server processes request and returns you pair of access and refresh token as JSON.

Copy 
{ "access_token" : "gAAAAFZrQSfYP1i0Spu9Y-hKcJTA9LtxnOz0L87Bhqvmo67S2vE8BGOiPbHT_op1fdl7",
   "expires_in" : 300,
   "refresh_token" : "ePhb!IAAAAGx2t6IcXULEBDNj_92zBK6BAhIBKr4JZccc2h1sC_HzoQAAAAEbd5WV81ijFO98hFubRaKtUCHDR",
   "scope" : "1095:*",
   "token_type" : "bearer"
 }

Access and refresh tokens

Initial authorization process involves action of your user to authorize your application. This authorization is permanent, but it can be revoked if user denied access to your application. The Trakopolis API server returns 2 tokens: permanent refresh token and access token.

  • Access token has short lifetime, equal to 5 minutes. Access token is used to get an access to protected resources (assets, statuses, alerts etc). All tokens are final and they can't be modified. After token is expired you need to get new one.
  • Refresh token represents user permission for your application and is used to get new access token without asking user to enter his credentials. You can get as many new access tokens as you want using refresh token, until user keeps your application authorized.

You must encrypt and securely store refresh token in permanent storage. If someone has an access to your application client identifier, client secret and refresh token, it can use your credentials to access Trakopolis API server.

Retrieve new tokens (using refresh token)

The Trakopolis API server requires that tokens should be frequently updated. An access token has 5 minutes lifetime and should be updated prior to its expiration. Process flow for refreshing an access token:

1. Your application makes a call for an access token /api/oauth2/token Client identifier, client password and refresh token must be passed.

  • Request URL: https://api.trakopolis.com/api/oauth2/token
  • Request Method: POST
  • Content-Type: application/x-www-form-urlencoded
  • Authorization: Basic WW91ckNsaWVudElkPT06WW91ckNsaWVudFNlY3JldA==
  • POST Data: grant_type=refresh_token&refresh_token=ePhb%21IAAAAGx2t6IcXULEBDNj_92zBK6BAhIBKr4JZccc2h1sC_HzoQAAAAEbd5WV81ijFO98hFubRaKtUCHDR

HTTP Basic authorization is calculated the same way as it was done during exchaging authorization code to token. You should also URLEncode refresh token value.

2. Trakopolis OAuth2 authorization server processes request and returns you JSON response with pair of new access and refresh tokens.

Copy 
{
  "access_token": "gAAAACiK8n1sB0FdDIje-HY_-CtpoL8o1IRuM9jl5qQlxzQ4xdmWWDpCe3TsNztfTEW",
  "expires_in": 300,
  "refresh_token": "ePhb!IAAAAHqAidsYnsSfrHxPGq3_ibjoQzboN7LlnWVNbSt-9KXOoQAAAAFO107PQ0N5LK6ceELfEiCpWbX8TEzKgPGDuG8adZHKK3hpogvMclakLew",
  "scope": "1095:*",
  "token_type": "bearer"
 }

It is important to make sure your application saves new refresh and access token and use them for all further requests. All tokens are final and the Trakopolis API server issues new tokens with every request. If access token is expired there is no way to use it in further requests, only new token must be issued.

You can get more details at OAuth2 RFC "6. Refreshing an Access Token"

Revoke authorization

External Webiste/Mobile application can force API server to revoke its authorization. This revokes current active authorization given for application and user, unsubscribes user from push notifications and removes all notification settings. Refresh token will no longer be valid. To revoke authorization, mobile application should do protected request (using access token)

Request URL: https://api.trakopolis.com/api/oauth2/revokeAuthorization

Request Method: POST

Headers: 

  • Authorization: Bearer <your access token> 
  • request-type: api  
  • response-type: application/json
Remarks
Old refresh tokens can become invalid if user of your application made new authorizations on new devices. To be safe you should use latest refresh token every time after you receive new access + refresh tokens.
See Also