Authorization
Akifast User Authentication
The Akifast application performs the necessary authorization for users to log in to merchant sites and freely navigate and shop on the site within the OAuth2 framework. The merchant must implement the authorization_code flow in the OAuth2 framework for the Akifast (Akinon) user to enter the merchant's website.
The following steps needs to be completed in this flow:
1. Redirecting User to the Login Page
The merchant initiates the flow with the Login with Akifast button placed on the login page. Clicking this button redirects the user to the Login page on the Akifast OAuth2 Server. When clicking the button, the merchant should redirect to the following address by appending the parameters in the table to the URI. This redirection occurs in a new tab.
Method: GET
Path: /oauth/authorize
Query Parameters
The parameters to be added to the authorization URL are provided in the table below.
| Parameter | Description |
|---|---|
| grant_type | This value must be assigned as authorization_code. |
| response_type | This value must be assigned as code. |
| client_id | The client_id value of the merchant using Akifast. |
| state | A boomerang value to be used by the merchant to match the response to the request. It is not a mandatory parameter. |
| redirect_uri | The URI to which the logged-in user will be redirected. |
Example Request
https://oauth.sandbox.akifast.com/oauth/authorize?grant_type=authorization_code&response_type=code&client_id={{client_id}}&state=HLa754Dj&redirect_uri=https%3A%2F%2Ftest-merchant.com%2Foauth-code-handler
The user redirected to the above URL reaches the Akifast OAuth2 Server's Login page. The user performs authentication on this page and grants permission to the merchant.
2. Getting an Access Token
To obtain an access token on behalf of the authenticated user who has granted permission to the merchant, the user is redirected to a URL that accepts the following parameters provided by the merchant.
| Parameter | Description |
|---|---|
| code | The code value to be sent to obtain the access token in the next step. |
| state | The boomerang value sent when the user was initially redirected. |
The merchant will send the above parameters to the URL provided by the merchant via URI Query.
The URL will be as follows:
https://test-merchant.com/oauth-code-handler?code=yCcm1Z&state=HLa754Dj
The merchant, upon receiving the request with the code parameter in the URL, should make a request to the following URL with the parameters below to obtain an access token on behalf of the user.
Method: POST
Path: ${oauth_server_url}/oauth/token
Content Type: application/x-www-form-urlencoded
NOTE
The Authorization header of the request must include the Basic Authentication method with the merchant ID and password.
Example Request
curl --location 'http://oauth.sandbox.akifast.com/oauth/token' \
--header 'Accept-Language: tr' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic OWQzNmVjMDQtZGUyZi0xMWVhLTg3ZDAtMDI0MmFjMTMwMDAzOllvdXJTZWN1cmVQYXNzd29yZCE=' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=EYDCPY' \
--data-urlencode 'redirect_uri=https://test-merchant.com/oauth-code-handler'
Query Parameters
| Parameter | Example Value | Description |
|---|---|---|
| grant_type | authorization_code | The value of grant_type in the request sent to the OAuth2 Server must be sent as authorization_code. |
| code | yCcm1Z | The code value received in the redirect URL must be sent. |
| redirect_uri | https://test-merchant.com/oauth-code-handler | The URI to which the logged-in user will be redirected. This redirect URI sent in the “Redirecting User to the Login Page” request must be the same. |
Example Response
{
"access_token": "{{jwt_formatted_access_token}}",
"token_type": "bearer",
"refresh_token": "{{jwt_formatted_refresh_token}}",
"expires_in": 3599999,
"scope": "read write update delete",
"user": {
"akinon_user_id": "{{akinon_user_id}}",
"phone_number": "+900000000000",
"email": "john.doe@example.com"
},
"jti": "2qMQ4eZD2Ce_s1L77S_JygcrYew"
}
Response Parameters
| Return Value | Description | Example Value |
|---|---|---|
| access_token | Token information used for making requests on behalf of the user. Returned as a JWT. | eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsmtpZCI6ImQ3OTdmZDA2LTQ2NmQtNGM1MS05N2RmLWZlYzdmZjAwMjlmOCJ9 ExUDO2FqkoTevLcpIstyXvNd1HejhxDq3t3uC5modp9mGdRZgmYH2zWMtAVVkEd |
| token_type | The type of the returned token. | bearer |
| refresh_token | Token used to refresh the user's access_token when it expires. It has a longer validity period than the access_token. | eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtZCI6ImQ3OTdmZDA2LTQ2NmQtNGM1MS05N2RmLWZlYzdmZjAwMjlmOCJ9 oKSLZFeEOjxax7cCzZ3RrYVGdRzUHfhU5koWsRhRnxXYIOI6KXLj__X3BXAav64psg45VlWMBipbjFmgk0o_1knTXCaglg4j3kk3xtwfmEVOkzqkj0dvJ2hYF61AvilSPcQV0lM1oUk |
| expires_in | The expiration time of the Access Token in seconds. | 3599999 |
| scope | The scopes for which the Access Token is valid. | read/write/update/delete user |
| user.akinon_user_id | The Akinon User ID of the user who owns the token. | F61C8BF00BFD4C7AFE459F24A358F2B |
| user.phone_number | The phone number of the user who owns the token. | +900000000000 |
| user.email | The email address of the user who owns the token. | john.doe@example.com |
| jti | A unique value generated for the request. | 2qMQ4eZD2Ce_s1L77S_JygcrYew |
With this response, the access_token obtained will be sent to the Akifast API with the Akinon-User-Access-Token header for all requests made on behalf of the Akinon user. The access_token can be stored by the merchant on the user's session and can be refreshed once with the refresh_token when the access_token expires.
3. Refreshing the Access Token
This method is used to refresh the access token when it expires.
Method: POST
Path: ${oauth_server_url}/oauth/token
Content Type: application/x-www-form-urlencoded
NOTE
The Authorization header of the request must include the Basic Authentication method with the merchant ID and password.
Example Request
curl --location 'http://oauth.sandbox.akifast.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic OWQzNmVjMDQtZGUyZi0xMWVhLTg3ZDAtMDI0MmFjMTMwMDAzOllvdXJTZWN1cmVQYXNzd29yZCE=' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token={{jwt_formatted_refresh_token}}'
Query Parameters
| Parameter | Example Value | Description |
|---|---|---|
| grant_type | authorization_code | The value of grant_type in the request sent to the OAuth2 Server must be sent as authorization_code. This identifies the flow. |
| refresh_token | eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCI... | Token used to refresh the user's access_token when it expires. It has a longer validity period than the access_token. |
Example Response
{
"access_token": "{{jwt_formatted_access_token}}",
"token_type": "bearer",
"refresh_token": "{{jwt_formatted_refresh_token}}",
"expires_in": 3599999,
"scope": "read write update delete",
"user": {
"akinon_user_id": "{{akinon_user_id}}",
"phone_number": "+900000000000",
"email": "john.doe@example.com"
},
"jti": "2qMQ4eZD2Ce_s1L77S_JygcrYew"
}
Response Parameters
| Return Value | Description | Example Value |
|---|---|---|
| access_token | Token information used for making requests on behalf of the user. Returned as a JWT. | eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6mQ3OTdmZDA2LTQ2NmQtNGM1MS05N2RmLWZlYzdmZjAwMjlmOCJ9 ExUDO2FqkoTevLcpIstyXvNd1HejhxDq3t3uC5modp9mGdRZgmYH2zWMtAVVkEd |
| token_type | The type of the returned token. | bearer |
| refresh_token | Token used to refresh the user's access_token when it expires. It has a longer validity period than the access_token. | eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVIsImtpZCI6ImQ3OTdmZDA2LTQ2NmQtNGM1MS05N2RmLWZlYzdmZjAwMjlmOCJ9 oKSLZFeEOjxax7cCzZ3RrYVGdRzUHfhU5koWsRhRnxXYIOI6KXLj__X3BXAav64psg45VlWMBipbjFmgk0o_1knTXCaglg4j3kk3xtwfmEVOkzqkj0dvJ2hYF61AvilSPcQV0lM1oUk |
| expires_in | The expiration time of the Access Token in seconds. | 3599999 |
| scope | The scopes for which the Access Token is valid. | read/write/update/delete user |
| user.akinon_user_id | The Akinon User ID of the user who owns the token. | F61C8BF00BFD4C7AFE459F24A358F2B |
| user.phone_number | The phone number of the user who owns the token. | +900000000000 |
| user.email | The email address of the user who owns the token. | john.doe@example.com |
| jti | A unique value generated for the request. | 2qMQ4eZD2Ce_s1L77S_JygcrYew |