WS Shop API: Security

SHR has introduced the use of OAuth 2.0/OpenID Connect bearer tokens for securing some of the Windsurfer APIs. As new functionality is added, it will also be secured using the bearer tokens. We will eventually be securing all API access this way. Current functionality that will be affected includes:

Group
GuestRequest
RateCalendar

General Flow

The following diagram shows the overall flow:

URLS

Environment	Authorization Server Token Endpoint URL	API Base URL
UAT	`https://iduat.shrglobal.com/connect/token`	`https://uatapi.shrglobal.com/`
Production	`https://id.shrglobal.com/connect/token`	`https://api.shrglobal.com/`

Windsurfer® Shop API Documentation

IDS Swagger - Groups, Guest Request and Rate Calendar

API Calls

Step I - Client requests an access token

Before calling the actual API, the caller is expected to first get an access token via the authorization server token endpoint URL using the “Client Credentials” flow, passing the unique client ID and secret issued by SHR.

Sample Request

POST https://iduat.shrglobal.com/connect/token
CONTENT-TYPE application/x-www-form-urlencoded
client_id=<ClientID>&client_secret=<ClientSecret>&grant_type=client_credentials&scope=<api scopes e.g. wsapi.guestrequests.read>

The authorization server token endpoint will return a JSON-formatted response. Calling applications are expected to cache the access_token and then send a request for another only after expiration period is passed.

Sample Token Response

{
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjI2QjY1RDQ2NjYzM0JFN0NENUFENjJDREFBOTM4RDQwN0Y4MTRGNUMiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJKclpkUm1ZenZuelZyV0xOcXBPTlFILUJUMXcifQ.eyJuYmYiOjE2MzMwMDcwNjMsImV4cCI6MTYzMzAxMDY2MywiaXNzIjoiaHR0cHM6Ly9pZHVhdC5zaHJnbG9iYWwuY29tIiwiYXVkIjpbImh0dHBzOi8vaWR1YXQuc2hyZ2xvYmFsLmNvbS9yZXNvdXJjZXMiLCJ3c2FwaSJdLCJjbGllbnRfaWQiOiJXU19BUFBfSUJFX0NDIiwic2NvcGUiOlsid3NhcGkuZ3Vlc3RyZXF1ZXN0cy5yZWFkIiwid3NhcGkuc2hvcC5yYXRlY2FsZW5kYXIiXX0.nsuB6Dfh6LBhR9BBt1ZjXxbVTXJlhh1x3vQxOJPU33naP7Lcr1fo_IXK466TMTM53zJOfYxKxqhRr85IpMQDnIDeJXAqLJGQB6Ah4j389W4STi0vCFy_rf9GuObfQwvuHMfy-I-QEPy4GehzxQYyuO-jG6MuUtuYfpxjEY72asDiYCPsDj7VnI6Vaj7ksTfUkb0WFEUn83crifn8OUvArVKpEyC_c2Dmmeepg_IxCdFnVEAXgC5cWrwqz4feYwsIrV8vTdqi3AFBfiscD7W3GaKsS5OU3W0yfx_oG5uxLdMJW1h3w5N-jWFHika0sAaeO1qopDdnPYBzWbJH1F5hMqYSJanYNhTt-RieqKNLeiaCVBjToCU909sBnqsFlMmP_tha3ng-6R6cnKPz4pmfM5JZZtmJR2tCOhJ_1UzyUWyz2cxoc1mZfA0MqzwISaBznaDkRSbMwyIi_BmeoX183iG0NNXhQfQyxDjGzVCQUtnSCAraUwiZ3bsA7t_QnjRiyxdSsHymo9pmN-A_kRcpj-fee_ZddOael-NClyxpxrHQ08k8WdJmeAUKzZpKcHiahytxQXWm7CELXoRY35N7yfhuOC13yt7nNjIF349C4i1zvd3phSYBjOkVUXT1U-RBfIrgkL3imENGcNRqu2ZJFvgUmdRNKFimFZso3x_QkAk",
    "expires_in": 3600,
    "token_type": "Bearer"
}

Response Attribute	Description
access_token	The value of the Access Token. This is what the client will need to access the APIs.
expires_in	The time period (in seconds) for which the access token is valid.
token_type	Type of token. In our implementation this will always be Bearer.

Sample error responses

{
    "error": "invalid_client"
}

Step II - Call the Windsurfer API while passing the access token

Once the caller obtains the access_token, they can then make calls to the protected WS APIs by passing it as a Bearer Token in the Authorization header of the HTTP request.

This sample call, which gets a list of available guest requests for a property, includes a bearer token in the Authorization request header.

GET https://apiuat.shrglobal.com/shop/guestRequest/ALMD?channelID=30&languageID=1
Authentication: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjI2QjY1RDQ2NjYzM0JFN0NENUFENjJDREFBOTM4RDQwN0Y4MTRGNUMiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJKclpkUm1ZenZuelZyV0xOcXBPTlFILUJUMXcifQ.eyJuYmYiOjE2MzMwMDcwNjMsImV4cCI6MTYzMzAxMDY2MywiaXNzIjoiaHR0cHM6Ly9pZHVhdC5zaHJnbG9iYWwuY29tIiwiYXVkIjpbImh0dHBzOi8vaWR1YXQuc2hyZ2xvYmFsLmNvbS9yZXNvdXJjZXMiLCJ3c2FwaSJdLCJjbGllbnRfaWQiOiJXU19BUFBfSUJFX0NDIiwic2NvcGUiOlsid3NhcGkuZ3Vlc3RyZXF1ZXN0cy5yZWFkIiwid3NhcGkuc2hvcC5yYXRlY2FsZW5kYXIiXX0.nsuB6Dfh6LBhR9BBt1ZjXxbVTXJlhh1x3vQxOJPU33naP7Lcr1fo_IXK466TMTM53zJOfYxKxqhRr85IpMQDnIDeJXAqLJGQB6Ah4j389W4STi0vCFy_rf9GuObfQwvuHMfy-I-QEPy4GehzxQYyuO-jG6MuUtuYfpxjEY72asDiYCPsDj7VnI6Vaj7ksTfUkb0WFEUn83crifn8OUvArVKpEyC_c2Dmmeepg_IxCdFnVEAXgC5cWrwqz4feYwsIrV8vTdqi3AFBfiscD7W3GaKsS5OU3W0yfx_oG5uxLdMJW1h3w5N-jWFHika0sAaeO1qopDdnPYBzWbJH1F5hMqYSJanYNhTt-RieqKNLeiaCVBjToCU909sBnqsFlMmP_tha3ng-6R6cnKPz4pmfM5JZZtmJR2tCOhJ_1UzyUWyz2cxoc1mZfA0MqzwISaBznaDkRSbMwyIi_BmeoX183iG0NNXhQfQyxDjGzVCQUtnSCAraUwiZ3bsA7t_QnjRiyxdSsHymo9pmN-A_kRcpj-fee_ZddOael-NClyxpxrHQ08k8WdJmeAUKzZpKcHiahytxQXWm7CELXoRY35N7yfhuOC13yt7nNjIF349C4i1zvd3phSYBjOkVUXT1U-RBfIrgkL3imENGcNRqu2ZJFvgUmdRNKFimFZso3x_QkAk

Sample API Output - Success

{
    "requestInfo": {
        "hotelCode": "ALMD",
        "hotelID": 14035,
        "languageID": 1,
        "channelID": 30
    },
    "guestRequests": [
        {
            "id": 684,
            "name": "Connecting room request for a new guest booking",
            "style": 1,
            "details": [
                {
                    "id": 1208,
                    "name": "",
                    "code": "ConRRq"
                }
            ]
        },
  ...
  ]
}

Sample API Output - Invalid / Missing Token

{
    "error": "invalid_token",
    "error_description": "This request requires a valid JWT access token to be provided"
}