You can use the OAuth 2.0 authorization code flow to securely acquire access tokens and refresh tokens for your client apps, which can be used to access resources that are secured by an authorization server. The authorization code flow exchanges an “authorization code” for access token and refresh token.

Authorization code

Authorization code is a random string generated by the authorization server and returned to the application as part of the authorization response. The authorization code is relatively short-lived and is exchanged for an access token at the token endpoint when using the  authorization code flow.

The client app wants to access protected resources in Tiki Marketplace that are not owned by it. It has to ask resource owners for permission to access their resources. 

Therefore, first, the client app makes an authorization request to the resource owner by redirecting that user to a page with an authorization proposal.

A dummy example of what an authorization proposal will look like

The authorization proposal must provide links to authorization endpoints with the following query params to request an authorization code:

Parameter	Description	Value (Example)
response_type	Always is code in Authorization code flow	code
client_id	Your app id	7590139168389961
redirect_uri	The redirect_uri of your app, where authentication responses can be sent and received by your app. It must exactly match one of the redirect URIs you registered in the OpenAPI console.	https://example.com/tiki/callback
scope	Desired scopes from seller	offline product order inventory
state	A value included in the request that is also returned in the token response. It can be a string of any content that you wish. A randomly generated unique value is typically used for preventing cross-site request forgery attacks.	Any random state with at least 8 characters

The authorization endpoint should look like 

Tiki token endpoint {auth_endpoint} – https://api.tiki.vn/sc/oauth2/auth

{auth_endpoint}?response_type=code&client_id=7590139168389961&redirect_uri=https%3A%2F%2Fexample.com%2Ftiki%2Fcallback&scope=offline%20product%20order&state=RJvROw5fL

If the resource owner agrees with that authorization request and “clicks to allow” Tiki, the resource owner will be redirected to the authorization endpoint of the Tiki Marketplace authorization server.

The Tiki Marketplace authorization server will authenticate the resource owner and ensure the resource owner’s consent with the request from the client app before returning a response to the user along with an authorization code.

Then, the user’s browser will automatically redirect to the redirect_uri that is declared in the query parameters of the above authorization endpoint.

In the case of success, you will receive an “authorization code” from parameters of the redirect_uri.

https://yourcallbackurl?code=wwxdZmftI2r0Xn5gbwX...&scope=offline%20product%20order&state=RJvROw5fL

In the case of failure, you will receive an “error code” and an “error hint” for the reason of failure.

https://example.com/tiki/callback?error=access_denied&error_code=403&error_hint=User%20denied%20the%20request

Your client has to handle the callback (redirect_uri) to get an authorization code or handle an error.

If you got authorization code, you could make an API request to the token endpoint along with that authorization code and client app credentials to access token and refresh token. These parameters you have to exchange with authorization server at token endpoint.

Name	Value	Description
grant_type	authorization_code	Fixed
code	wwxdZmftI2r0Xn5gbwX…	This authorization code is returned from the redirection
client_id	7590139168389961	Your app id
redirect_uri	https://example.com/tiki/callback	The redirect_uri of your app
client_secret		Send client secret in basic header or request body, see Token endpoint auth method

Token endpoint auth method

When you make an API request to the token endpoint, there are multiple ways of authenticating OAuth 2.0 clients at the token endpoint. Tiki Marketplace provides 2 ways for you to choose when creating an application (“basic header” and “request body”). When exchanging credentials with the token endpoint, you must use the exact token endpoint auth method. For example, the above API request uses the “basic header” token endpoint auth method. To learn more about token endpoint auth method, see Token endpoint auth method

The API request should look like (The following example uses the basic header method)

Tiki token endpoint {token_endpoint} – https://api.tiki.vn/sc/oauth2/token

curl --location --request POST '{token_endpoint}' \ 
--header 'Authorization: Basic NzU5MDEzOTE2ODM4OTk2MTp0ZlNsMGM2...' \ 
--header 'Content-Type: application/x-www-form-urlencoded' \ 
--data-urlencode 'grant_type=authorization_code' \ 
--data-urlencode 'code=wwxdZmftI2r0Xn5gbwX...' \ 
--data-urlencode 'redirect_uri=https://example.com/auth/tiki/callback' \ 
--data-urlencode 'client_id=7590139168389961'

Finally, you got an access token and a refresh token. You should store your tokens (access token and refresh token) somewhere safe and make requests to retrieve protected resources with access token.