Authentication

All Zahir Online API need to be Authenticated using an Authentication Token. You can obtain an Authentication Token with the following ways:

Using OAuth 2.0

Overview

Public applications use the standard 3 legged OAuth process where a user can authorise your application to have access to their Zahir organisation.

Public applications can either be web based or desktop/mobile installed. Access tokens expire after 30 minutes.

How to register an application

  1. Login to the Zahir Developer portal
  2. Go to the My Applications > Add Application screen to add your application.
  3. Select “Public” and enter a name for your application and the redirect URL.
  4. You get client ID for use with your application.
Access Tokens

If you want longer access to the organisation, you will need the user to re-authorize your application. To request access token user must have account Zahir ID. Account Zahir ID is Zahir's SSO to access APIs and Apps.

Use this option to receive an access_token to the API if you have an application that runs on a Web browser, or Mobile Application that is able to display embedded Web Browser. For instance: showing login Android’s WebKit.

There are 2 steps, you need to get the code and then the access_token.

a. First step is to get the code:

For example:

https://account.zahir.id/oauth/authorize?response_type=code&client_id=[YOUR_CLIENT_ID]&redirect_uri=[YOUR_REGISTERED_REDIRECT_URI]&state=[ANY_RANDOM_STATE]{&scope=[OPTIONAL_SCOPE]}

Case:

For Desktop or Mobile application, you may set the redirect URI with https://account.zahir.id/oauth/receive_authcode_next. If success, the redirect URI will contains a page that shows user ‘to close this window’. From that you need to get the code from HTML title. The form will be: Success [CODE]

For web application, you may set the redirect URI with YOUR_CALLBACK_URL that is registered in the list of Zahir.Id Application . If success, the redirect YOUR_CALLBACK_URL will contains a HTTP GET parameter code that contains the code to exchange in second step below.

b. Use the code in step (a) to get the access_token with POST request, set the grant_type to authorization_code:

For example (curl):

curl -F grant_type=authorization_code -F code=[CODE_FROM_STEP_A] -F redirect_uri=[YOUR_REGISTERED_REDIRECT_URI] -F client_id=[YOUR_CLIENT_ID] -F client_secret=[YOUR_CLIENT_SECRET] -X POST https://account.zahir.id/oauth/access_token

From that you will get response similar to:

{ 'access_token' : [YOUR_ACCESS_TOKEN], 'token_type' : 'Bearer', 'expires_in' : [TIME_EXPIRES_IN_UNIX_TIMESTAMP] }