Issuing a code / token

  • In order to be authenticated via the OAuth, you must first have a code and a token issued.
  • This guide walks you through the development process for issuing codes and tokens.

Issuing code

  • A code must first be issued in order to have the Access Token issued, which is required for the API call.
  •  
  •   - Delivered via a web browser.
  •   - The issued code can be used in exchange for an Access Token.
  •   - The code will expire 1 minute after issuance.
  •   - The code used when requesting the Access Token cannot be reused.
  •  
  •  
  • - Code issuing request format and sample
Request format via web browser

https://{{mallid}}.cafe24api.com/api/v2/oauth/authorize?response_type=code&client_id={client_id}&state={state}&redirect_uri={redirect_uri}&scope= {scope}

Request format via web browser
Key Discription Required
response_type Fixed at "code" string value. Required
client_id App Key (= Client ID) issued when creating the app in the Developer Center Required
state Typically, you enter a randomly generated unique value to prevent CSRF attacks.
This value is delivered when the code is redirected.
Recommended
redirect_uri The URI to redirect the code
It must exactly match one of the Redirect URLs (s) you register, except that it must be encoded in a URL.
Required
scope ',' can be used to specify scopes. Required
  • If you have not logged in, you will be redirected to the login window. Once you log in, the account will be valid for 2 hours, so if you have successfully logged in within 2 hours, the screen for agreement / approval will be promptly displayed.
  •  
  •  
  • - Response format and sample for code issuance
  • Enter the code as a query string and redirect it to redirect_uri. Then the redirect_uri request is processed to grant a code.
Response format

HTTP/1.1 302 Found
Location: {redirect_uri}?code={authorize_code}&state={state}


Response sample

HTTP/1.1 302 Found
Location: https://test.com/oauth/callback?code=L2KXlmXeWS9W5q08ybH1XH&state=xyz

Response format and sample
Key Description Required
code Authentication code Required
state If the request contains a state parameter, the same value should also appear in the response.
This value helps prevent CSRF attacks against clients.
Required
  •  
  • - Error Response format and sample
  • Provides an error response to redirect_uri.
Error Response format

HTTP/1.1 302 Found
Location: {redirect_uri}?error={error}&state={state}&trace_id={trace_id}


Error Response sample

HTTP/1.1 302 Found
Location: https://test.com/oauth/callback?error=invalid_scope&state=xyz&trace_id=d4b00c5d0f9954be49af24560deda83d

Error Response format and sample
Key Description
error The error code value defined in section 4.1 of the OAuth 2.0 authorization framework.
error_description A detailed description of the error.
state If the request contains a state parameter, it will provide the same value in response.
trace_id A unique serial number for tracking errors.
Error Response format and sample
Error code What happens How to fix errors
invalid_request When requesting without client_id, redirect_uri, scope value Check the missing values.
When requesting with the wrong client_id, scope, redirect_uri Check the app information you created in the Developer Center.
unsupported_response_type When the requested response_type value is missing or it is not a ‘code’ Make sure that "response_type = code" is specified.
invalid_scope The requested range is invalid, unknown or malformed. Make sure you called it with the scope information you registered when you created the app in the Developer Center.
access_denied If you are not logged in as the manager account We guide the app user to log in as the administrator account.

Issuing token

  • You can use the code to get the Access Token you need to actually call the API.
  •   - The code must be issued prior to the Access Token.
  •  
  •  
  • - Request format sample for token issuance
Request format

POST /api/v2/oauth/token
Authorization: Basic {base64_encode({client_id}:{client_Secret})}


Request sample

curl -X POST \
'https://{{mallid}}.cafe24api.com/api/v2/oauth/token' \
 -H 'Authorization: Basic S3hWd2RCTjdPVk5uQjNGMHM3UzFNRDpFaEZnM0xYak1KR21BZWV5MUliaXhI' \
 -H 'Content-Type: application/x-www-form-urlencoded' \
 -d 'grant_type=authorization_code' \
 -d 'code=xu2xG1rfDimVP2oe6fopRE' \
 -d 'redirect_uri=https://test.com/oauth/callback'

Issuing tokne request format and sample
Key Description
grant_type Fixed to string value ‘authorization_code‘
code Code obtained from the code issuance above.
redirect_uri Identical redirect_uri value used in code issuance.

  •  
  • - Response format and sample for token issuance
  • Receive a Refresh Token that can be used to renew the Access Token, its expiration time, or the token itself.
Response sample

HTTP/1.1 200 OK
  {
   "access_token": "HVBVuQgjIRUGHE5CBOiKRGC",
   "expires_at": "2018-01-08T19:15:21.981",
   "refresh_token": "euIChI80BQWWCJEiwTHWCrG",
   "client_id": "KxVwdBN7OVtnbS3F0s7S1MD",
   "mall_id": "{{mallid}}",
   "user_id": "{{mallid}}",
   "scopes": [
     "mall.read_product",
     "mall.read_store"
   ],
   "issued_at": "2018-01-08T17:15:22.083"

  }

Issuing token Response format and sample
Key Description
access_token Access Token required for API calls.
expires_at Expiration date and time of Access Token
refresh_token Used to reissue expired Access Tokens.
client_id Client ID
mall_id Mall ID
user_id User ID
scopes List of scopes that have accepted permissions
issued_at Date of issue

  •  
  • - Error Response format and sample
Error Response sample

HTTP/1.1 400 Bad Request

{
    "error":"invalid_grant",
    "error_description":"It is a wrong code."
}
Error Response format and sample
Key Description
error The error code value defined in section 5.2 of the OAuth 2.0 authorization framework.
error_description A detailed description of the error.
Error Response error code
Error code What happens How to fix errors
invalid_client When requesting without client_id, client_secret values Make sure that you entered the authorization value in the header.
invalid_request When requesting without redirect_uri, code values Make sure there is no missing value in the request.
unsupported_grant_type When the requested grant_type value is missing or it is not the ‘authorization_code’ Make sure that grant_type = authorization_code is specified.
invalid_grant When requesting with wrong client_id, client_secret, redirect_uri Check the app information you created in the Developer Center.
When requesting with an incorrect code Make sure that the code is the same code issued and authenticated.
When requesting with an expired code Please refer to the code issuance and proceed with issuing a new code.