Authentication

<Amadeus Hospitality.> developer portal

Using AHWS Authentication

AHWS provides an authentication service which allows you to access all the other APIs. This document outlines the steps a client application would use to interact with all APIs in AHWS. We'll cover all the bases from initial authentication to details about refreshing tokens.

 
NOTE: Refresh token expiration times have changed since the creation of this video. Refresh tokens expire after 72 hours.

Authenticating in for the first time

To start, you will need to authenticate with AHWS to receive an access token and a refresh token. An application needs the following items in order to interact with the authentication API:

  • client_id - Provided by Amadeus Hospitality
  • client_secret - Provided by Amadeus Hospitality
  • password - This is the password of the Amadeus Hospitality User Not your API Management password
  • username - This is the username of the Amadeus Hospitality User Not your API Management username

In order to perform the client operations, there are up to three possible actions:

  1. Acquire an access token and a refresh token
  2. Call the service while presenting the access token
  3. Refresh the access token when it expires or becomes invalid

Acquire an access token and a refresh token

In order to acquire a token, you first have to call the Authentication API with a POST request. Amadeus Hospitality recommends always passing your subscription key as a header attribute in all calls made that require it.

Type: HTTP POST

Request URL

https://api.newmarketinc.com/2.0/OAuth2/AccessToken

Request header example

    Content-Type: application/json
    Ocp-Apim-Subscription-Key: [Your-Subscription-Key]
        

Request body example (JSON)

{                     
	"client_id": "[clientidvalue]",
	"client_secret": "[clientsecretvalue]",
	"grant_type": "password",
	"password": "[passwordvalue]",
	"username": "[usernamevalue]"
}
					

Response body example (JSON)

           
{
	"access_token": "1cBZBtY4Nfcrx/PlVf+nmGgiUbZdMPLWM0g4Qh4r5y5KQOoVhshYRNihi4/ja6p+CZ2hNEih2t/YR7UL6pn7iw0QisRDZKD032dSzB70DKiOWREYX+hH+IRphp8E/Ip
	DUhDVHr8acEj6TH0sPoHMQr7F06WTbzcCBjomrY8YOcBs1h9pdyFS9nYXb1RARxoicX24QjkRWfjfbXmJvaJ3Rg9kNVGAVIboZWDZ6n176MSazjM0WteAs5UdsmB70qB6HHmzbF5+jmoKcqQ1
	UHpjLfqxUvcOO3HyIz71tR04gldO3/e1mfOMSPTeesoAXU3quYcjcGeY2s+gf5jlURnZWosB4xyPtacXwEV0bdL+3ppi+iQRFhiDK0cvbdo/DgkwRzJm0KfJWl31WL9EsHYe2I0jv3xMByooIc
	o7LH6DKsYRqW7RAXA5bZX4pFf+aVRCgV6vjXWg5WIUbnAOZnzpPUtMSJIKnEVal63e8+UHS4R9ToEI1bm7wNPxgk9O1Bf4Cw8DlsuQWTuhhXg/mVMeIMZuWlQBUkU3nZYZWtSGCZ+CRISBMySgF
	IMadxF/AVJd9Xo0uy9nck20tlBQRuprssxPd9VZI5GPOCOQkgBTOZGNdanAdVt9emZYYANnYRt5",
	"expires_in": 900,
	"refresh_token": "GXwOwRlXc54zVafcV8NyscDS1AvIUTHBifQwv8TDZsX3mEq1hEKjoWegwgErlhnJftoTA+FrBwb70Am07kQzD572h+mAbN\/XTMu\/eVHtQ4vwQhp7fkPwyCitAVhMsGvi
	QjfV4Y8AiQGIAVXPhvBVXzX7RLEds64jtBdGriNbG9twFUFfLIuBEYZuspTs3AIeUrhVjQzP8f5kYMKtir+XH4+ogrdDIMQ4u8YXuc91oseH77tS+8s0qRclDJeGVcysSR2n3gxI6TvsHWDRI\/AE
	J\/Haq\/XE5eoS1QxpDkk+kn5ciAOGd2BY58pgJnd5LwSb\/N1uFEj\/1pB4J5F1oxUt5Ruq68w\/qvVGdWorPyngKyPNKe4DjZ++SyJFbQqN75as6NCEUjdzpU\/7zyXXD5+57OkhJFAaliraXfAz
	2jzUD4PW3yeEtQuIIOwL8kmjcsIm10OGfWuvl+6nLo6gg4wF+sY4MWct0Jt\/J6Mog65W4bSed8q5r2QLNrOClEJp+pwAEh9qkbtvDgVTfTJzhDrDvr0U7dyqdQEYqo4lmqGRBJIC7QhCYN31tbYs
	JAVAp+UM+0G4bKY6FxlIrB7mKg\/Zm+RvUx4cBVlyuw1UtWzxV3DEwHP4pAoLFEzs6CWkgFECx8a3\/ETd86ivlMcM15Wy0mm9uXoW6Qcr3Y5hrmho\/BU9SKk2Fyq0fY8r0hhiCGl55TU6rF8yLAE
	EvIdxSsHEiLynywGUhD6xAhyKYKyzk5wbp\/XzE8eneezEFWuRmUJJ",
	"token_type": "bearer"
}
				

The JSON payload in the response body contains 4 elements:

  • access_token – the access token value
  • expires_in – the number of seconds until the token expires
  • token_type – this will always be “bearer”
  • refresh_token – the refresh token value

From the JSON payload, extract the access_token and refresh_token values to use with your requests to the secured service. If you are caching the token for multiple calls, use the expires_in value as the cache expiration.

Call the service while presenting the token

In order to call the service with the token, extract the access_token value from the response and pass it in the Authorization header in your request to the secured service like this OAuth [access_token].

Request header sample


    Content-Type: application/json
    Ocp-Apim-Subscription-Key: [Your-Subscription-Key]
	Authorization: OAuth 1cBZBtY4Nfcrx/PlVf+nmGgiUbZdMPLWM0g4Qh4r5y5KQOoVhshYRNihi4/ja6p+CZ2hNEih2t/YR7UL6pn7iw0QisRDZKD032dSzB70DKiOWREYX+
	hH+IRphp8E/IpDUhDVHr8acEj6TH0sPoHMQr7F06WTbzcCBjomrY8YOcBs1h9pdyFS9n
	YXb1RARxoicX24QjkRWfjfbXmJvaJ3Rg9kNVGAVIboZWDZ6n176MSazjM0WteAs5UdsmB70qB6HHmzbF5+jmoKcqQ1UHpjLfqxUvcOO3HyIz71tR04gldO3/e1mfOMSP
	TeesoAXU3quYcjcGeY2s+gf5jlURnZWosB4xyPtacXwEV0bdL+3ppi+iQRFhiDK0cvbdo/DgkwRz
	Jm0KfJWl31WL9EsHYe2I0jv3xMByooIco7LH6DKsYRqW7RAXA5bZX4pFf+aVRCgV6vjXWg5WIUbnAOZnzpPUtMSJIKnEVal63e8+UHS4R9ToEI
	1bm7wNPxgk9O1Bf4Cw8DlsuQWTuhhXg/mVMeIMZuWlQBUkU3nZYZWtSGCZ
	+CRISBMySgFIMadxF/AVJd9Xo0uy9nck20tlBQRuprssxPd9VZI5GPOCOQkgBTOZGNdanAdVt9emZYYANnYRt5
					

This header should be coupled with a body that meets the requirements of that API you are accessing. With this header, AHWS will allow you access to the products you subscribe to. This access token will expire after the expires_in timeframe is exceeded. At this point you will receive a 403 - Forbidden response from AHWS and will be required to retrieve a new access token.

Http Authorization Headers are an industry standard and adhere to the following format:

Authorization: [type] [credential]

Note that in the header we are specifying an Authorization Type of OAuth and our credential in this case is the access_token from the response payload.

Refresh the access token when it expires or becomes invalid

Access tokens expire in a relatively short time frame, determined by the expires_in value. You can account for this time frame and automatically refresh your access token or you can wait until you get a 403 - Forbidden to go through the refresh process. Either way will work.

Type: HTTP POST

Request URL

https://api.newmarketinc.com/2.0/OAuth2/RefreshAccessToken

Request header example

    Content-Type: application/json
    Ocp-Apim-Subscription-Key: [Your-Subscription-Key]

The parameters for this request are:

  • grant_type – should always be set to “refresh_token”
  • refresh_token - the refresh token received from the initial credentials request for the access token

Request body example


{
	"grant_type": "refresh_token",
	"refresh_token": "GXwOwRlXc54zVafcV8NyscDS1AvIUTHBifQwv8TDZsX3mEq1hEKjoWegwgErlhnJftoTA+FrBwb70Am07kQzD572h+mAbN/XTMu/eVHtQ4vwQhp7fkPwyCitAV
	hMsGviQjfV4Y8AiQGIAVXPhvBVX+YDyo4Aa+/trLNw7EhPJ4dTKRSWqCEwS0jZDjuD+ij7XBiylwh8ixCQWla6grlhej2sKvTCYSBi4kWehbka4OlGfy8NJddacBynZmC9hmuhQTn8Gz2
	ZQIqYTYXslG/3yDw3eQkr/xocQ9tci3wbsE9Q0pgJmSDB8pK8MtLWqY8jv8HcwD7VG+q3mE8HTuINwzYeL4US/9b1PmCS7tS6iNAwWXojViAcBIBhPlOYovLOI8Q0+uKa2xpmKNi1ftcq
	511KzJQZCyenzAGMlds0okRULqyuuYTuGg4bsl3vnALGqvCv21Y/Lz7hHt3sAeR/rFrWTbkheW9RkAjKMVKzn6f+InC8yizbnlWlWhbn2gKfN1GUlI5eNMY+C2n8TDDSnqCsD0hYxlYVMk
	Q2xB5FyQYud73vk/E2+vxlLRl0yhjd/R0wBv4L7TKOfJRBozWkJ9+Q8RGRGdcXvefUeQ+qx7sEqbFi2kNK3cvWkGta8bfiOUY/ntxrjKvNMWqG8UlH+Va4qfDKnNThZXV5KK8ooRjaR2LDo
	0mgWTGTylTZPGZwt5s/7GmZbwc1fE5+TMLmefYppGH67jgxCnnQT4OZTyr87RDCRbe2kz7LuqQNffW8"
}

And this is what the response will look like. It delivers you a new access token along with your refresh token. Use the new access token to continue calling other APIs, keeping the refresh token for the next authentication refresh.

Response body example

           
{
	"access_token": "1cBZBtY4Nfcrx/PlVf+nmGgiUbZdMPLWM0g4Qh4r5y5KQOoVhshYRNihi4/ja6p+CZ2hNEih2t/YR7UL6pn7iw0QisRDZKD032dSzB70DKiOWREYX+hH+IRphp8E/Ip
	DUhDVHr8acEj6TH0sPoHMQr7F06WTbzcCBjomrY8YOcBs1h9pdyFS9nYXb1RARxoicX24QjkRWfjfbXmJvaJ3Rg9kNVGAVIboZWDZ6n176MSazjM0WteAs5UdsmB70qB6HHmzbF5+jmoKcqQ1
	UHpjLfqxUvcOO3HyIz71tR04gldO3/e1mfOMSPTeesoAXU3quYcjcGeY2s+gf5jlURnZWosB4xyPtacXwEV0bdL+3ppi+iQRFhiDK0cvbdo/DgkwRzJm0KfJWl31WL9EsHYe2I0jv3xMByooIc
	o7LH6DKsYRqW7RAXA5bZX4pFf+aVRCgV6vjXWg5WIUbnAOZnzpPUtMSJIKnEVal63e8+UHS4R9ToEI1bm7wNPxgk9O1Bf4Cw8DlsuQWTuhhXg/mVMeIMZuWlQBUkU3nZYZWtSGCZ+CRISBMySgF
	IMadxF/AVJd9Xo0uy9nck20tlBQRuprssxPd9VZI5GPOCOQkgBTOZGNdanAdVt9emZYYANnYRt5",
	"expires_in": 900,
	"refresh_token": "GXwOwRlXc54zVafcV8NyscDS1AvIUTHBifQwv8TDZsX3mEq1hEKjoWegwgErlhnJftoTA+FrBwb70Am07kQzD572h+mAbN\/XTMu\/eVHtQ4vwQhp7fkPwyCitAVhMsGvi
	QjfV4Y8AiQGIAVXPhvBVXzX7RLEds64jtBdGriNbG9twFUFfLIuBEYZuspTs3AIeUrhVjQzP8f5kYMKtir+XH4+ogrdDIMQ4u8YXuc91oseH77tS+8s0qRclDJeGVcysSR2n3gxI6TvsHWDRI\/AE
	J\/Haq\/XE5eoS1QxpDkk+kn5ciAOGd2BY58pgJnd5LwSb\/N1uFEj\/1pB4J5F1oxUt5Ruq68w\/qvVGdWorPyngKyPNKe4DjZ++SyJFbQqN75as6NCEUjdzpU\/7zyXXD5+57OkhJFAaliraXfAz
	2jzUD4PW3yeEtQuIIOwL8kmjcsIm10OGfWuvl+6nLo6gg4wF+sY4MWct0Jt\/J6Mog65W4bSed8q5r2QLNrOClEJp+pwAEh9qkbtvDgVTfTJzhDrDvr0U7dyqdQEYqo4lmqGRBJIC7QhCYN31tbYs
	JAVAp+UM+0G4bKY6FxlIrB7mKg\/Zm+RvUx4cBVlyuw1UtWzxV3DEwHP4pAoLFEzs6CWkgFECx8a3\/ETd86ivlMcM15Wy0mm9uXoW6Qcr3Y5hrmho\/BU9SKk2Fyq0fY8r0hhiCGl55TU6rF8yLAE
	EvIdxSsHEiLynywGUhD6xAhyKYKyzk5wbp\/XzE8eneezEFWuRmUJJ",
	"token_type": "bearer"
}
				

If the refresh token is invalid or expired, you will receive a 403 - Forbidden. In this case, you need to present your full credentials again.

Invalid requests

HTTP Status Codes

Reason

400 Invalid request due to bad parameter values <
  
{
  "error": "invalid_request",
  "error_description": "null",
  "grant_type": "null",
  "error_uri": "null"
}
											
403 Unknown Username or Incorrect Password
  
{
  "error": "access_denied",
  "error_description": "null",
  "grant_type": "null",
  "error_uri": "null"
}
											
403 Improper client id or client secret
  
{
  "error": "unauthorized_client",
  "error_description": "null",
  "grant_type": "null",
  "error_uri": "null"
}
											
405 Method not allowed due to GET instead of POST

Javascript usage examples

In order to perform the client operations from Javascript in a browser, the following requirements should be met:

  1. Browser supports localStorage (HTML5)
  2. The following libraries are included
    • TokenManagement.js
    • Configuration.js
  
<script type="text/javascript" src="assets/js/ns/Configuration.js"></script>
<script type="text/javascript" src="assets/js/ns/TokenManagement.js"></script>
			

The main functions supporting the token management are in TokenManagement.js. This library will allow the user to validate credentials against AHWS, receive access and refresh tokens, and manage the expiration and clearing of tokens.

Configuration.js holds the environment settings and clientid/secret information.

Token Acquisition

There are two ways to get an access token from AHWS, you can present credentials to the Authentication Service or you can present a refresh token to the Authentication Service which was acquired from presenting credentials initially.

To get the original access token and refresh token, call the GetTokensForCredentials function.

  
function GetTokensForCredentials(clientId, clientSecret, userName, password, successCallback, errorCallback)