Authentication

Every API call should pass authentication. There are 3 authentication options available:

- anonymous

- authentication  via client_id 

 

Contact NCSI to provide you an additional information that you need to use in order to authenticate app. This information contains:

- App id
- App secret
- Authorize url
- Access token url

Authentication via client_id

Application can authenticate itself by passing its application key via client_id query string parameter or through Autorization header

GET http://data.gov.om/api/1.0/meta/dataset/OMAGLS2016/dimension/Country?client_id=APP_ID

OAuth authorization

Knoema uses OAuth 2 to provide authorized access to its API. It also support client and server side authentication flows.

 

Client-flow authentication

To begin the flow either popup a new window or redirect the user's browser to:

GET https://data.gov.om/oauth/authorize
response_type=token
&client_id=APP_ID
&redirect_uri=YOUR_URI
&scope=SCOPE

The user will then be prompted to authorize your application. If the user chooses to authorize your application, the user will be redirected to:

YOUR_URI#access_token=USER_ACCESS_TOKEN&expires_in=NUMBER_OF_SECONDS_UNTIL_TOKEN_EXPIRES

If the user chooses not to authorize your application, the user will be redirected to:

YOUR_URI#error=access_denied&error_description=The resource owner denied the request

 

Server-flow authentication

To begin the flow either popup a new window or redirect the user's browser to:

GET https://data.gov.om/oauth/authorize
?response_type=code
&client_id=APP_ID
&redirect_uri=YOUR_URI
&scope=SCOPE

The user will then be prompted to authorize your application. If the user chooses to authorize your application, the user will be redirected to: 

YOUR_URI?code=CODE
Once the user has authorized your app, you should make a server side request to exchange the code returned above for a user access token.
GET https://data.gov.om/oauth/token
?grant_type=authorization_code
&client_id=APP_ID
&client_secret=APP_SECRET
&code=CODE
&redirect_uri=YOUR_URI

If there is an issue exchanging the code for a user access token, the authorization server will return the error as a JSON object in the body of the response:

{
     "error": "incorrect_client_credentials"
}

If code was exchanged successfully server will return a JSON object

{
    "access_token": "ACCESS_TOKEN",
    "token_type": "bearer",
    "expires_in": "86400",
    "refresh_token": "REFRESH_TOKEN",
    "scope": "SCOPE"
}

Note:  if redirect_uri is specified in app settings it should match the redirect_uri that passed in oauth request.

 

Basic authentication

To authenticate request pass "Authorization" header:

Authorization: "Knoema " + appId + ":" + base64(HMACSHA1(appSecret) + ":1.2";

 

Description:
appId - id of your app

appSecret - secret code of app
base64 - function that converts bytes array to base64 format
HMACSHA1 - crypto algorithm created from bytes array. This array should be created from current date in the following format "dd-MM-yy-HH" e.g. "30-09-16-19"

 

Example in c# code:

1
2
3
4
5
6
7
8
9
10
11
12
// make instance of crypto service https://msdn.microsoft.com/en-us/library/system.security.cryptography.hmacsha1(v=vs.110).aspx
var hashAlgorithm = new HMACSHA1(Encoding.UTF8.GetBytes(DateTime.UtcNow.ToString("dd-MM-yy-HH")));
 
// make a hash and convert to base64
var value = string.Format("Knoema {0}:{1}:1.2", appId, Convert.ToBase64String(hashAlgorithm.ComputeHash(Encoding.UTF8.GetBytes(appSecret))));
 
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", value);
 
// make you request here