OAuth
The NTRglobal API supports OAuth mechanism for authenticating users. If you are not familiar with OAuth we recommend reading the guide at Hueniverse http://hueniverse.com/oauth/

Depending on which language you are using, there may be a suitable OAuth client library you can use. See a list here http://oauth.net/code/

You may create an application in our developer portal. Upon creation of a new application you will be given a consumer key and secret, which can be used to make authenticated requests to our API.

NTRglobal API supports two mechanisms for receipt of OAuth authentication parameters:

  • As a query element in the URL
  • In Authorization Header

The OAuth request cycle is divided in three basic steps

  1. Retrieve a request token
  2. Request user authorization by sending the user to a NTRglobal login page
  3. Exchange the request token for an access token

The flow varies slightly when using a desktop application with what's called the "PIN-mode flow".
This diagram illustrates further:

OAuth Authentication flow used by NTRadmin

1. Retrieve a request token
The first step in the OAuth process is obtaining a request token and requesting a token secret. The NTRglobal API request token endpoint is

https://apifree.ntrglobal.com/oauth/request_token You may specify a callback URL in the request. You will need to temporarily store both the token and secret, as you will need to use them in a later step

Example

GET /oauth/request_token?oauth_callback=oob&oauth_consumer_key=opz4OjgMZ1NST2b8F6UQ&oauth_nonce=1603VIG8&oauth_signature_method=HMAC-SHA1&oauth_signature=OAEw%2F2NnCZx3m6AurJSYxIOPZQ8%3D&oauth_version=1.0&oauth_timestamp=1285152365 

HTTP/1.1 

Host: apifree.ntrglobal.com
ParameterValue
oauth_consumer_keyThe Consumer Key.
oauth_signature_methodThe signature method the Consumer used to sign the request.
oauth_signatureThe signature
oauth_timestampTimestamp
oauth_nonceAn ID that cannot repeat with the same timestamp
oauth_versionOPTIONAL. If present, value MUST be 1.0 . Service Providers must assume the protocol version to be 1.0 if this parameter is not present. Service Providers' response to non-1.0 value is left undefined.
oauth_callbackAn absolute URL to which the Service Provider will redirect the User back when the Obtaining User Authorization (Obtaining User Authorization) step is completed. If the Consumer is unable to receive callbacks or a callback URL has been established via other means, the parameter value MUST be set to oob (case sensitive), to indicate an out-of-band configuration.
Additional parametersAny additional parameters, as defined by the Service Provider.
The Service Provider checks the signature and responds with:

oauth_token=R5SjEhuZNYF7sfKm61af&oauth_token_secret=y6CJvg4q6sVUW8h6r69gYJ5v77LxeLUv09p41jQt&oauth_callback_confirmed=true
ParameterValue
oauth_tokenThe Request Token
oauth_token_secretThe Token Secret
oauth_callback_confirmedMUST be present and set to true. The Consumer MAY use this to confirm that the Service Provider received the callback value.
Additional parametersAny additional parameters, as defined by the Service Provider.
2. Directing the user to authorize your application
Once your application has obtained a request token and token secret, you may direct the user to NTRglobal API authorize URL.

https://apifree.ntrglobal.com/oauth/authorize
This will ask the user to authorize your application

GET /oauth/authorize?oauth_token=R5SjEhuZNYF7sfKm61af

HTTP/1.1

Host: apifree.ntrglobal.com
3. Obtaining an access token
When a user returns to your application you should then exchange the request token for an access token and secret. NTRglobal API access token endpoint is

https://apifree.ntrglobal.com/oauth/access_token
GET /oauth/access_token?oauth_verifier=I4TGXICfAaBd64WMRsMQ&oauth_token=R5SjEhuZNYF7sfKm61af&oauth_consumer_key=opz4OjgMZ1NST2b8F6UQ&oauth_nonce=QMxx4AHF&oauth_signature_method=HMAC-SHA1&oauth_signature=1T4lSgHqYwH9ZPjRtXLqtaiW0RM%3D&oauth_version=1.0&oauth_timestamp=1285152381

HTTP/1.1

Host: apifree.ntrglobal.com
ParameterValue
oauth_consumer_keyThe Consumer Key.
oauth_tokenThe Request Token obtained previously.
oauth_signature_methodThe signature method the Consumer used to sign the request.
oauth_signatureThe signature as defined in Signing Requests (Signing Requests).
oauth_timestampTimestamp
oauth_nonceAn ID that can't repeat with the same timestamp
oauth_versionOPTIONAL. If present, value MUST be 1.0 . Service Providers MUST assume the protocol version to be 1.0 if this parameter is not present. Service Providers' response to non-1.0 value is left undefined.
oauth_verifierThe verification code received from the Service Provider in the Service Provider Directs the User Back to the Consumer(Service Provider Directs the User Back to the Consumer) step.
You need to store this access token and secret for all your users that will use your application to access NTRglobal resources so you only need to do this authentication process only at the beginning or if you revoke the credentials in your application.