Obtain Access and Refresh Tokens Using Authorization Code Grant

This authorization grant provides a method to issue access token and refresh token for third-party applications. In order to request tokens from this endpoint, make sure you meet the following requirements:

Have a registered and active OAuth application with Luxstay and have access to provided Client ID.
Because this endpoint simulate a redirection-based flow, the client must be capable of interacting with the resource owner's user-agent, for example, via a web browser, and receving requests via redirection.

Authorization Flow

Luxstay uses OAuth 2.0's authorization code grant flow to issue access tokens on behalf of users. Below is the abstract flow graph that demonstrate the basic steps of the authorization code grant flow.

Authorization Code Grant Flow

1 - Sending Users To Authorize

Your application should redirect users to the following URL:

https://api.luxstay.com/oauth/redirect

The following values should be passed as GET parameters:

client_id - issued when you created your application
scope - permissions associated with the request

For example:

curl \
  --request GET \
  --url 'https://api.luxstay.com/oauth/redirect?client_id=5aadcf38-6f86-41e3-8601-4efe00c30d75&scope=room:read,room:write'

1
2
3

The scope parameter is a comma-separated list of OAuth scopes indicating which parts of user's account your application wants to access. Please refer to this section for more information.

2 - Verifying User Identity

Next, the user need to verify his account registered with Luxstay. He may choose to authenticate via username/password or through social authentication. Currenly, only Facebook and Google authentication are supported.

3 - Approving Or Denying The Request

The user will be redirected to a page where he can review the authorization request for example the client information, and the list of requesting scopes. The user is then asked to accept or deny the your application to access his's account.

Request Authorization

The following parameters should be included in the request:

client_id - issued when you created your application
redirect_uri - URL to redirect back to, provided when you created your application
response_type - explicitly be code in this case
scope - permissions associated with the request

If the user denies your request, Luxstay redirects back to your redirect_uri with an error parameter. Your application should handle this situation appropriately.

http://api.luxstay.com/oauth/callback?error=access_denied

If the user approves your request, he will be redirected to the redirect_uri with a verification code (authorization code). Specifically, a code parameter should appear in the GET request. This verification code is then used to exchange for an access token. If everything is correct, the access token and refresh token will be generated and sent back to you:

{
    "data": {
        "token_type": "Bearer",
        "expires_in": 432000,
        "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImZiMTIxNWU5YzNjMzkxMzg2ZTgyODgxMjBiMWI5ODhiYTIxNGVhMDRkNjdjMzQ3OTAyM2RhMjJmMTBmYTMyMzA3OTE5Mjg0ZmE4YTRiYjBiIn0.eyJhdWQiOiIwMzE4YTU5Yy0zMmZkLTQ0ODMtOTQ4NC0xZWQ0YTQ4NmNkOGYiLCJqdGkiOiJmYjEyMTVlOWMzYzM5MTM4NmU4Mjg4MTIwYjFiOTg4YmEyMTRlYTA0ZDY3YzM0NzkwMjNkYTIyZjEwZmEzMjMwNzkxOTI4NGZhOGE0YmIwYiIsImlhdCI6MTUzOTg1MDE1MSwibmJmIjoxNTM5ODUwMTUxLCJleHAiOjE1NDAyODIxNTEsInN1YiI6IjEwMTMwIiwic2NvcGVzIjpbXX0.LScAU_e2gIH_8E-ww2VbkjP74Xpjcnf_3C9yoDOFeBqNbbCDrSrnhH8gyoV-PZH49sy5ttUw1DBYzSV4v0hmU-ZXCA-6CeTe5EzwIMEWPRHy24cgCV_Pml6vddpoPl_p5DZE_7wUWarMiLAorkyIhp09s8rAjDtoYwXPT_pQ_zIV8t4YYLpcXPROeVM2uJdHDphaVOIfaCW45wS2atDUWiKVYw1M_1uADRPv0laf-m7OuyVwJmCqe82KIwldoFOIltfr19LUDfS8YJ0XXZh5uvY0mLTMA0HMqO0QBvOlPTJavhzYU7LBfhMHdUglMmUQujvjcMFoSGcKSXmLkVV-Pl8Aw4Xhd4tI1Jg7Kr_HarOZ4cAgXEpwR_GjEI6VPB2qiKAtTCtzceNjSapz9ODeOZ0A18b92KVVXLTVQa0kFOts_EyD_ZBkgt9OsD5XGU_yfzuA2zZyK-F9Yrz3ddocjvL3amCShzY3i9guFfktBZ1EMBAG_8Ar8lwWotDU_yTCYYt035Jv07JTwLVajY8Y_pY2DSVYswGAFPZYv4twpJmQB0wr_InNeRu9c9EI3ciktmkuP6GPrMR9JeX2gcEISJ_2iJQrDhUapWeahd3qm2yed_CD7dysqnM0bDeM1_QippydSZcRfTiSjACbQaVf5679LW8cqytfCDMaJR5jNyU",
        "refresh_token": "def50200ce02aaff8af8612614ecd4f87542993fa18703950c1f502e709843b98d38604490c71f3a13fe677d2cb7d64db6055fc30f478b31eb3d0c530af70bc34750be3d0c2a797c3360a8199ce92837088f36c98a678d7c9d1fc7265118e4b2131304b610260cf89f567f917d6823152ed1ef59a3c4bb5b9767152b8bfc25a9308fc06076c371038f2c90235b147267d8ae44986bf2a8e3bfab5d0266fce19e3049c203d89bfda4ba35b3c5924f029501e37c39e3d044d003b31c580fece9331b521c55ad993d295b5f006836060793d29aa9de8a5c9586ff3cabb00493522d7e3486835ecfe11525226ff23c6938de1d9bd38a018a53f2e0a97982b7280452be72fa5b982c924545235cbb789024683784450858e7b0a3b8ce510988ca598bb2849479af3307067a79c0e18a58311bc3c566fdb1f27783d2d8af826d13d9e6655f8e93e639365fd19fc86b11598a47c8baaad19cca4db4c317b36ff6b3d70ccf6f2b0b85d688176a0fec87f674c7b0212b3e7cc1a83eb5cb5c1c1ec00846811e1cfed0294bcbee"
    }
}

1
2
3
4
5
6
7
8

Endpoint

Method	URI	Headers
GET	/oauth/redirect	None

URL Params

Param	Description	Type	Required
cliend_id	The UUID of the OAuth Client	String	Yes
scope	The comma-separated list of token scopes	String	No

Request & Response Examples

Because this endpoint requires redirection flow, the response may not always be JSON. However, for simplicity, all responses will be demonstrated using JSON here.

Successful Response

200

Example response

{
    "data": {
        "token_type": "Bearer",
        "expires_in": 432000,
        "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImM3ODVjOGNjYThkZjZmMjA0YTZiOWVhMDIzZDhkOTIyOWI3MzgxODIxM2VhNmNiMmI4MzJmZDg5YWY5MzlhMGY5MGI4ZjVhNTU2NTJiOWI1In0.eyJhdWQiOiIwMzE4YTU5Yy0zMmZkLTQ0ODMtOTQ4NC0xZWQ0YTQ4NmNkOGYiLCJqdGkiOiJjNzg1YzhjY2E4ZGY2ZjIwNGE2YjllYTAyM2Q4ZDkyMjliNzM4MTgyMTNlYTZjYjJiODMyZmQ4OWFmOTM5YTBmOTBiOGY1YTU1NjUyYjliNSIsImlhdCI6MTUzOTgzODY0NywibmJmIjoxNTM5ODM4NjQ3LCJleHAiOjE1NDAyNzA2NDcsInN1YiI6IjEwMTMwIiwic2NvcGVzIjpbXX0.L5QDT2SbwbjtFIA-PEg9fmVqV4HbWBSc4lR9Bl3LcQJrktJ87jqxPkGk0l1FzHSiuAxKf_1M_UhNWGdWkb5tDiIkr3Oz__19MOeFTZKwFHRFbzbV7TK7BTc3NAQoAKfw-QFy0zkC07WIr_EJMG_RW2FtSKfVRzA0g4sn8l3wH2ZOHjWldggGpkpgtrfpTNnhWsC261HkYHPMG3ODWswLCnHQzG_VklKGCvPxH_V68Q9CFucvyoDi8nczlEorKRnPuot6I69g8cA9wvDHpKtW7onmQetrvcSwmkgWvncdqVI2yOFRzoFVaPaQ1sj_IFLIbB2ZSwJvTUwL0kUktzsc9jrY4fdbvF6qHV1BOGMJQVobNN1t-kt0pccMBJwedRqJtbRaPiK9KOqZRkpryaCcBd-A2erqZKFUaZMUfQUYyj532oG7HWeiKWp4YSUuUkKxDiwyn0jzHBGQICJ48z2RUehdV51VfAyJxvZAsnR_ANdfmfRrmGGMdqunk1fz4-veGxn3rejcTy3iphWOMy96VChbvvS3pBUi5DQgofn24YYINYV2I2WWaqEgWP2pSB9LKqLO-GcDnza0QhCJ2UIZeYcbkwaFdmsj41onJ2-Vl2BnI-WSpU067zKQTnGkHEUWG3pPMslxB95Hflw8Rr5OzNLL69TsagnxaSyzqMdWPEw",
        "refresh_token": "def50200340b2a8efdeea15b96ac09feb4fc2344e058ba3c1a78cba65e766b951f967cd5c9912540c3c21743a142fe4a3f8c58fd566193eb1e3d8c80165dcb50ea309c9ba07b8480050ec7a6b2acf16bb18d466938080b8a05990b324a26f447079f809fc1b8f6033f0d8c309de35718f2848cca2c991111cc2a83b97d8325c49195881a122b803b5e80c05e807d706951a85fd1775b7f070dda197239f9eb1bd0b19ea0ef6c73aadc5edb1d0e17b35bcc2d09ef0e7c699367263bc81090879d96733a5aaed3fdb29ac606f9cb7fc21e7f98e853688928f80ecd0ae2bba6b2126a48713bffabd72f0dfd99a1396d4818836dd65bbfafe40d4133962ca4eddc4a3f5dd50bd9dcd818ff4616b0c6e2e64fdd71d802ef7f19b7bb599059add5af4338b76a1546456ced8f521cc9848a77b3026dd800c8a3b3442410cc8c126761766ebfdc50381f9496cebbc1b7cdad6da2c6217c388cae0767dcb58ead015a229d22adb9b7d60425d981fd895a4105cc159554d1f41c675fbd179511c3977c14da870d39e27c6f4f1e"
    }
}

1
2
3
4
5
6
7
8

Error Response

401

Reason invalid client

Example response

{
    "message": "The client information you provided is invalid. Please try a different information or contact Luxstay for more information."
}

1
2
3

References

Authorization code grant specification

# Obtain Access and Refresh Tokens Using Authorization Code Grant

# Authorization Flow

# 1 - Sending Users To Authorize

# 2 - Verifying User Identity

# 3 - Approving Or Denying The Request

# Endpoint

# URL Params

# Request & Response Examples

# Successful Response

# 200

# Error Response

# 401

# References