OAuth2 guide

Askara use the OAuth2 framework to secure communications between third party apps and Askara app. If you never used this framework, please check out the OAuth.com documentation They have an excellent playground guide that takes you through the different steps required for establisling a connexion between the two apps.

Prerequisites

Before heading to the Step 1 of this guide, make sure you have a client id and client secret key pair. If you don't, please contact us so that our team generates an application for you. Make sure to give the redirection URL that your app will support when authentication succeeds (or fails).

Step 1 : Build the authorization URL and redirect the user to the authorization server

Before authorization begins, your application should first generates a random string to use for the state parameter. Your app will need to store this state to be used in the next step. The user that wants to authentify with Askara API must then follow the given URL (after replacing placeholders with your values) :

https://app.askara.loc/authorize?
  response_type=code
  &client_id=CLIENT_ID
  &redirect_uri=REDIRECT_URL
  &scope=profile%20organization
  &state=STATE

If you are already logged in, you will see the authorization page listing the required scopes. If not, then you will first have to login to Askara with your account. Once on the authorization page, click "Authorize" to allow the connexion. Askara will then redirect the user to your application (on the redirect url specified).

Step 2 : After the user is redirected back to the client, verify the state matches

The user was redirected back to the client, and you'll notice a few additional query parameters in the URL:

?state=STATE&code=CODE

You need to first verify that the state parameter matches the value stored in your app in step 1, so that you protect against CSRF attacks. Depending on how you've stored the state parameter (in a cookie, session, database, or some other way), verify that it matches the state that you originally included in step 1.

Step 3 : Exchange the authorization code for an access token

Now you're ready to exchange the authorization code for an access token. Your app needs to now build a POST request to the token endpoint with the following parameters:

POST https://api.askara.ai/oauth2/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "CODE",
  "redirect_uri": "REDIRECT_URL",
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET"
}

Here's the response from the token endpoint! The response includes the access token and refresh token.

{
  "token_type": "Bearer",
  "expires_in": 86400,
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN"
}

Great! Now your application has an access token, and can use it to make API requests on behalf of the user. You can use the website (https://jwt.io/)[https://jwt.io/] to analyze the access token content.

Step 4 : Refresh the access token

After some time, your access token will automatically expire and you API calls will fail. This is a security feature of the OAuth2 to avoid giving long life tokens to users, in case they become compromised.

To deal with this situation, you can get a new access token using the previously obtained refresh token that you should store somewhere in you application (in your database for example). Simply call the same token endpoint with different parameters to obtain a new access token :

POST https://api.askara.ai/oauth2/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "REFRESH_TOKEN",
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET"
}

Here's the response from the token endpoint, again the response includes the access token and a new refresh token.

{
  "token_type": "Bearer",
  "expires_in": 86400,
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN"
}

Make sure to store the new refresh token as the old one will not be valid anymore. That's it, you have setup everything to let your users connect safely with Askara API.