OVERVIEW
The Authorization Code Grant Type is used by Websites and Mobile Apps. It differs from most of the other Grant Types by first requiring the App to launch a browser to begin the flow.
In order to Authenticate your User via the Authorization Code, you just have to follow 4 steps :
- Your Application send your User to the Authentication Page.
- Your User enter their credentials (and can be prompted to approve the scopes for your app)
- Your User is redirected back to your Application with an authorization code in the query string
- Your Application exchanges the authorization code for an access token
STEP 1: REDIRECT YOUR USER TO THE ACCOR LOGIN PAGE
You have to redirect your User’s browser to the Accor Login page.
Then, once redirected:
- if the user is authenticated, you're done.
- if the user is not yet authenticated, the member is presented with Accor’s authentication page.
Request:
Type | Endpoint |
---|---|
GET | https://login.accor.com/as/authorization.oauth2 |
Parameters:
Name |
Value |
Required |
---|---|---|
response_type | The value of this field should always be code | Yes |
client_id | The appId key value generated when you register your application. | Yes |
redirect_uri | The URL your users are sent back to after authorization. | Yes |
scope | URL-encoded, space-delimited list of member permissions your application is requesting on behalf of the user. Scopes will be provided by Accor Team. |
Yes |
state | A value used to test for possible CSRF attacks | No |
nonce | String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. If present in the ID Token, Clients MUST verify that the nonce Claim Value is equal to the value of the nonce parameter sent in the Authentication Request. If present in the Authentication Request, Authorization Servers MUST include a nonce Claim in the ID Token with the Claim Value being the nonce value sent in the Authentication Request. Authorization Servers SHOULD perform no other processing on nonce values used. The nonce value is a case sensitive string. | No |
prompt | Used to display the authentication page (empty) or not (none). Use prompt=none when the user is already authenticated on another website (e.g. all.accor) | No |
ui_locales | Language code (2 digits) | No |
persistent | Should be yes for activating the “remember me” checkbox | No |
request | A single, self-contained parameter; a signed JWT whose claims represent the request parameters of the authorization request | Yes if “required signed requests” has been set on your clientid |
Example of Request:
GET https://login.accor.com/as/authorization.oauth2?response_type=code&client_id={your_client_id}&redirect_uri=https://yourdomain/callback&scope={list_of_scopes}
Accor login page:
STEP 2: YOUR USER IS REDIRECTED TO YOUR CALLBACK URL
After your User is signed in on Accor, he will be redirected automatically to your callback URL with the authorization code and state, that you sent in your request.
Request:
Type | Endpoint |
---|---|
GET | https://yoursite/Callback_URL |
Parameters:
Name |
Value |
Required |
---|---|---|
code | The OAuth2 authorization code | Yes, if authenticated |
state | A value used to test for possible CSRF attacks | No |
error | A code indicating the authorization error | No |
error_description | A URL-encoded textual description that summarizes the error | No |
STEP 3: RETRIEVE YOUR ACCESS TOKEN
You need to POST a request using the authorization code given during the previous step.
Request :
Type | Endpoint |
---|---|
POST | https://login.accor.com/as/token.oauth2 |
Header :
Headers |
Value |
Required |
---|---|---|
Content-Type | application/x-www-form-urlencoded | Yes |
Authorization* | The value of this field should always be: Basic {authorization} | Yes |
*authorization = Base64Encode(client_id:client_secretKey) or use standard tools to generate it (login=client_id, password=client_secretKey)
Parameters :
Name |
Value |
Required |
---|---|---|
grant_type | The value of this field should always be authorization_code | Yes |
code | The OAuth2 authorization code | Yes |
redirect_uri | The URI your users are sent back to after authorization. | Yes |
ACCESS TOKEN RESPONSE
A successful access token request returns a JSON object containing the following fields :
- access_token – The access token for the application. This value must be kept secure as specified in the API Terms of Use.
- Refresh_token – The refresh_token for the application. This value must be kept secure as specified in the API Terms of Use.
- Id_token – Identification token use with nonce parameter. The Id_token payload contains:
- pi.sri: session identifier. This filed is populate only after the authentication, not on the refresh endpoint
- nonce sent in parameter
- expires_in – The number of seconds remaining until the token expires. Currently, all access tokens are issued with a 15 minutes lifespan.
- token_type – Value: Bearer
An unsuccessful one returns an HTTP 400 with a JSON error object :
- invalid_client – Client authentication failed.
- invalid_grant – Authorization code has already been used or does not exist.
- unauthorized_client – The customer does not have authorization for the code grant stream or discount tokens.
- unsupported_grant_type – Returned if grant_type is different from authorization_code or refresh_token.
Example of Request :
POST https:// login.accor.com/as/token.oauth2
Content-Type: application/x-www-form-urlencoded
Authorization: Basic authorization
grant_type=authorization_code
code={authorization_code}
redirect_uri=https://yourdomain/callback
Example of Response :
{
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjdjWVJ3Y2Q5aGxJbFF5UktXX3lfMDBzOUM2OCJ9.eyJzdWIiOiIxNjUxMTU4QSIsImF1ZCI6ImFsbC5hY2NvciIsImp0aSI6ImkxMUp6MWUxMkFaT0pZOTFpOWI1a2giLCJpc3MiOiJodHRwczovL3BpbmdmZWRlcmF0ZS5kZXYtYWNjb3IuZXUxLnBpbmcuY2xvdWQiLCJpYXQiOjE2MDI3Nzk5MjgsImV4cCI6MTYwMjc4MDIyOCwiYXV0aF90aW1lIjoxNjAyNzc5OTI4fQ.UyDyEUcSok0pGSqE2ugUMY7SjIRreOqqbqFhsgpDl6sNqQwUdIxbO4rk5eM3K3MP6UEMqO0U1L0q980RjkAhidrahQms0ynB0GxPxZ4HiMgVNk0PmPxVXLU7N7Hv6tSoZQKZqV_mBB5cFRY4wt-E0LQmsuzv-xgXD3kmIVsL-RP3yO7fuBpUXj_dUUcdjsWv8KooTnAUUL5cGwUTOLXYviCRjTcpQOS_zB1VB6bka4BL4H11giiU_M9OKBOTLe6IbPkAWcchJhXb0OWhIAze6rhGQ0GyFFL1dBAKSFjr4TX3fMKPgGpmYXZ3oEC97fbNpy4KcYXlMeiaiw82CxgqIw",
"access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IlBJTkdRRFNGR1RSMjREWDI2NzdYWFhhYWFRZWVlIiwicGkuYXRtIjoiemU4dyJ9.eyJzY3AiOiJvcGVuaWQgQVBJV0VCLlVTRVIuUkVBRF9QUk9GSUxFIEFQSVdFQi5VU0VSLldSSVRFX1BST0ZJTEUgQVBJV0VCLlVTRVIuV0FMTEVUIiwiY2xpZW50SWQiOiJhbGwuYWNjb3IiLCJwbWlkIjoiMTY1MTE1OEEiLCJjb250YWN0SWQiOiIxMDAwMDExMTg1MDA4ODIiLCJ0b2tlbl91c2UiOiJhY2Nlc3MiLCJleHAiOjE2MDI3ODcxMzF9.V4FLElN3i4XT6JJYYqbRIqz0kxVNN1iqUIhaDMqLYQ4vlZaNNbTG8GOrQjigq0mAVCWrUpdqA-jGQHJyTd-2WKm5_sj52JOGOMmybMjf5em4UHIvznAO95LHOe_wimI9ELpJ5finxzYWntANhkIKSKwz5KBbS3vJ8-awm1VcXiIsMp1W92Ox3bHLMxvAsZbt9_-Uy0q5liVMoBjYnQmY8GHs6u5DFjOCC2wxn2K8M4z414glYgZqkGYVaDVAb-SwfPpsFRM7Zol99H-FOLqN0aQq0Jx32-_SDb3HP8RteFeyqYkuqcgNF5_lt2HN0mzUuIu1krqjmnSob6cV1deZ3w",
"refresh_token": "MSRlfbRbqn6GgaSJdhNxjrGEl1dkTXR7lYPvCNPjb7",
"expires_in": 7199,
"token_type": "Bearer"
}
Example of Error Response :
httpError = 401 UNAUTHORIZED
{
"error_description":"Invalid client or client credentials.",
"error":"invalid_client"
}
REFRESHING ACCESS TOKENS
Access tokens have a limited lifetime (1 hour). Using the authorization code flow, access tokens can be easily renewed using the refresh token obtained at the same step. To get a new access token, you must call the refresh endpoint.
Request :
Type | Endpoint |
---|---|
POST | https://login.accor.com/as/token.oauth2 |
Header :
Headers |
Value |
Required |
---|---|---|
Content-Type | application/x-www-form-urlencoded | Yes |
Authorization* | The value of this field should always be: Basic {authorization} | Yes |
*authorization = Base64Encode(client_id:client_secretKey) or use standard tools to generate it (login=client_id, password=client_secretKey)
Parameters :
Name |
Value |
Required |
---|---|---|
grant_type | The value of this field should always be refresh_token | Yes |
code | The OAuth2 authorization code | Yes |
refresh_token | The refresh token previously obtained | Yes |
Response :
A successful refresh token request returns a JSON object containing the following fields:
- access_token – The access token for the application. This value must be kept secure as specified in the API Terms of Use.
- refresh_token – The refresh_token for the application. This value must be kept secure as specified in the API Terms of Use.
- Id_token – Identification token use with nonce parameter
- expires_in – The number of seconds remaining until the token expires. Currently, all access tokens are issued with a 15 minutes lifespan.
- token_type – Value: Bearer
An unsuccessful one returns an HTTP 400 with a JSON error object:
- invalid_client – Client authentication failed.
- invalid_grant – The refresh token has been revoked
- unauthorized_client – The customer does not have authorization for the code grant stream or discount tokens.
- unsupported_grant_type – Returned if grant_type is different from authorization_code or refresh_token.
Example of Request:
POST https:// login.accor.com/as/token.oauth2
Content-Type: application/x-www-form-urlencoded
Authorization: Basic authorization
grant_type=refresh_token
refresh_token={refresh_token}
After each refresh, you need to check the session status. For security reason, this endpoint can be called once every 5 secondes for a same pi.sri. Otherwise, you will get an NO_VALID_SESSIONS response.
Request:
Type | Endpoint |
---|---|
GET | https://login.accor.com/pf-ws/rest/sessionMgmt/sessions/{pi.sri} |
Header :
Headers |
Value |
Required |
---|---|---|
Content-Type | application/json | Yes |
X-XSRF-HEADER | Against XSRF | |
Authorization | The value of this field should always be: Basic {authorization} | Yes |
Parameters:
Name |
Value |
Required |
---|---|---|
pi.sri | The pi.sri of the id_token. Example : K0KMSh-pR1SoXCSbYwtvd8kprYo.ZXUtY2VudHJhbC0x.XI8u |
Yes |
Response :
A successful request returns a JSON object containing the following fields :
- sri – pi.sri.
- status – session status
- HAS_VALID_SESSIONS : active session
- SESSION_REVOKED : revoked or disconnected session
- NO_VALID_SESSIONS : unknown or unvalid session
An unsuccessful one returns an HTTP 400 with a JSON error object:
Example of KO reponse :
{"resultId":"validation_error","message":"Validation error(s) occurred. Please review the error(s) and address accordingly.","validationErrors":[{"message":"The format of the SRI is invalid.","fieldPath":"sri","errorId":"session_mgmt_sri_invalid"}]}
Authentication with scopes approval mode
Authentication in approval mode consist of asking the user to validate each scopes he allows the clientId/partner.
To use this mode, use the prompt parameter: prompt=consent
This mode is not activated yet.