OAuth 2.0 Authorization Documentation
Table of Contents:
OAuth 2.0 is a protocol that lets your app request authorization to private data within a hotel chain’s group in Rover Connect.
Before getting started you will need to register your application in the Rover Connect API Developer Portal. After your app is registered and approved by the StayNTouch team you will receive a unique Client ID and Client Secret which will be used in the OAuth flow. The Client Secret should never be shared.
Hints:
- Your application should never pass any sensitive information as URL parameter (e.g. client secrets, authorization codes, bearer tokens). All sensitive information should be encrypted and passed through SSL.
Additional OAuth Documentation
Below are some helpful links if you need more help navigating OAuth and using it together with your application.
Authentication Methods
Your Client ID and Client Secret will be configured for one of two API authorization methods. Method 1, access through authorization code, can be configured for use for multiple hotel chains and groups within Rover while Method 2 is restrictive to a single hotel chain.
Method 1: Authorization Code
Hotel chain resource owners are able to grant your application access to their data by providing their login credentials to our authentication microservice. Hotel chain resource owners are users within a hotel chain who have been granted the role of "API User".
- Your web or mobile app should redirect users to the following URL where they will be presented with a StayNTouch login page:
https://auth.stayntouch.com/oauth/authorize
The following values should be passed as GET parameters:
client_id - issued when you created your app (required)
redirect_uri - URL to redirect back to (required). The authorization code and state will be sent to the redirect_uri upon authorization. The redirect_uri must be over HTTPS and accept the url parameter "code" and "state" (if the state is in the request).
response_type - must by “code”
state - unique string to be passed back upon completion (optional)
Example
- https://auth.stayntouch.com/oauth/authorize?client_id=2671339ab5f6768fd686671903fadca0f4f352c5de02d4b7bf709a8aec4d42fb&redirect_uri=https://myapp.com/&response_type=code&state=mycode
Client Views
Step 1: Provide Login Credentials
Step 2: Grant Access
After the client provides their credentials and grants access to their data on our service, a unique authorization code will be sent to your application. Using this authorization code, your application can request a token and refresh token through our authentication microservice.
- Your application can request a bearer token through the following URL:
https://auth.stayntouch.com/oauth/token
The following values should be passed in the POST body:
client_id - issued when you created your app (required)
client_secret - issued when you created your app (required)
grant_type - in this case, “authorization_code”
code - authorization code received in the initial authorization request
{
"access_token": "79465ced575bbde8e481fa507ee831022fb7f6671aee2723ac7d5e1c48c4816a",
"token_type": "bearer",
"expires_in": 2591999,
"refresh_token": "77a9a472c350c0a06d63f38ad9decf7aef7d2ed060b9ca3b79ef26c2ee0fca3b",
"created_at": 1503673005
}
Using this token, your application will have access to a client’s data and available APIs for 30 days, this token should be passed in all requests over SSL.
Hints:
Authorization codes expire after 10 minutes.
Tokens are unique to a single hotel chain. You will need to go through the authorization process for all hotel chain that connect to your application.
To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport.
If a token becomes compromised, tokens need to be revoked immediately. Then, in order to receive a new token you will need to go through the authorization process again to receive a new authorization code and a new token.
Tokens can be revoked through the oauth/revoke method
Revoking Active Tokens
You revoke an active bearer token through the following URL:
https://auth.stayntouch.com/oauth/revoke
The following values should be passed in the POST body:
client_id - issued when you created your app (required)
client_secret - issued when you created your app (required)
token - access token to be revoked
If the access token is revoked successfully you will received a 200 OK response.
Retrieving a New Token (Authorization Code Method Only)
After 30 days your token will expire and you will need to request a new token.
- Your application can request a new bearer token through the following URL:
https://auth.stayntouch.com/oauth/token
The following values should be passed in the POST body:
client_id - issued when you created your app (required)
client_secret - issued when you created your app (required)
grant_type - in this case, “refresh_token”
refresh_token - refresh token issued from your previous token request
Hints:
- In order to prevent interruption in API service, it is best to automatically renew tokens before the token expires every 30 days.
{
"access_token": "79465ced575bbde8e481fa507ee831022fb7f6671aee2723ac7d5e1c48c4816a",
"token_type": "bearer",
"expires_in": 2591999,
"refresh_token": "77a9a472c350c0a06d63f38ad9decf7aef7d2ed060b9ca3b79ef26c2ee0fca3b",
"created_at": 1503673005
}
Method 2: Client Credentials
If your application is unique to a single client. You can gain access to a client’s data by simply passing your Client ID and Client Secret to oauth/token.
Your application can request a bearer token through the following URL:
https://auth.stayntouch.com/oauth/token
The following values should be passed in the POST body:
client_id - issued when you created your app (required)
client_secret - issued when you created your app (required)
grant_type - in this case, “client_credentials”
{
"access_token": "2f7625c258c92ba53cdc1cbcaadef1eda7356ac9c0e6339b6540bd4edd1f1a48",
"token_type": "bearer",
"expires_in": 2592000,
"created_at": 1503584493
}
If your client_id and client_secret are configured correctly, our authentication microservice will include an access token that can be used to access your client’s APIs and data. All tokens expire after 30 days. After 30 days, you can request a new token by passing in your Client ID and Client Secret into (https://auth.stayntouch.com/oauth/token).
Hints:
To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport.
If a token becomes compromised, tokens will need to be revoked immediately. You can then get a new token at any time by calling oauth/token and passing parameters (grant_type => “client_credentials”)
Tokens can be revoked through the oauth/revoke method
Revoking Active Tokens
You revoke an active bearer token through the following URL:
https://auth.stayntouch.com/oauth/revoke
The following values should be passed in the POST body:
client_id - issued when you created your app (required)
client_secret - issued when you created your app (required)
token - access token to be revoked
If the access token is revoked successfully you will received a 200 OK response.
Retrieving a New Token (Client Credentials Method Only)
After 30 days your token will expire and you will need to request a new token.
- Your application can request a new bearer token through the following URL:
https://auth.stayntouch.com/oauth/token
The following values should be passed in the POST body:
client_id - issued when you created your app (required)
client_secret - issued when you created your app (required)
grant_type - in this case, “client_credentials"
Hints:
- In order to prevent interruption in API service, it is best to automatically renew tokens before the token expires every 30 days.
{
"access_token": "2f7625c258c92ba53cdc1cbcaadef1eda7356ac9c0e6339b6540bd4edd1f1a48",
"token_type": "bearer",
"expires_in": 2592000,
"created_at": 1503584493
}