코드/토큰 발급받기

  • OAuth를 통한 인증을 받기 위해서는 코드발급과 토큰발급을 우선 진행해야 합니다.
  • 본 가이드에서는 코드발급과 토큰발급에 대한 개발가이드를 안내하고 있습니다.

코드 발급

  • API 호출에 필요한 Access Token을 발급 받기 위해 code를 먼저 발급 받아야 합니다.
  •  
  •   - 웹브라우저를 통해 전달됩니다.
  •   - 발급 받은 code를 이용해 Access Token으로 교환 가능합니다.
  •   - code는 발급 후 1분이 경과하면 만료됩니다.
  •   - Access Token 발급 요청시 사용된 code는 재사용 할 수 없습니다.
  •  
  •  
  • -코드 발급 Request 형식 및 샘플
웹 브라우저를 통한 Request 형식

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

코드 발급 Request 형식
Key 설명 필수여부
response_type "code" 문자열 값으로 고정합니다. 필수
client_id 개발자센터에서 App 생성시 발급받은 App key (=Client id) 필수
state 일반적으로 CSRF 공격을 방지하기 위해 임의로 생성된 고유 값을 입력합니다.
코드 리다이렉트시 해당 값이 전달됩니다.
권장
redirect_uri "코드를 리다이렉트 해줄 URI
URL로 인코드되어야 한다는 점을 제외하고 등록한 Redirect URL(s) 중 하나와 정확히 일치해야 합니다.
필수
scope ","로 사용권한 지정이 가능합니다. 필수
  • 로그인이 된 적이 없다면 로그인 창으로 리다이렉트 됩니다. 한번 로그인한 계정은 2시간 동안 유효함으로 2시간 이내에 로그인을 성공한 적이 있다면 바로 동의/허가를 위한 화면이 나타납니다.
  •  
  •  
  • - 코드 발급 Response 형식 및 샘플
  • 코드를 쿼리 스트링으로 담아 redirect_uri로 리다이렉트 합니다. redirect_uri 요청에 대해 처리하여 code를 얻도록 합니다.
Response 형식

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


Response 샘플

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

코드 발급 Request 형식
Key 설명 필수여부
code 인증 코드 필수
state 요청에 state 매개 변수가 포함되어 있으면 동일한 값이 응답에도 나타나야 합니다.
이 값은 클라이언트에 대한 CSRF 공격을 방지하는 데 도움이 됩니다.
필수
  •  
  • - Error Response 형식 및 샘플
  • redirect_uri에 오류 응답을 제공합니다.
Error Response 형식

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


Error Response 샘플

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

Error Response 형식 및 샘플
Key 설명
error OAuth 2.0 권한 부여 프레임워크의 섹션 4.1에 정의된 오류 코드 값입니다.
error_description 오류에 대한 자세한 설명입니다.
state 요청에 state 매개 변수가 포함되어 있으면 응답시 동일한 값을 제공합니다.
trace_id 오류를 추적하기 위한 고유 일련번호입니다.
코드 발급 Error Response 코드
Error 코드 발생하는 사례 오류 해결 방법
invalid_request client_id, redirect_uri, scope 값을 누락하여 요청한 경우 누락된 값을 확인하십시오.
잘못된 client_id, scope, redirect_uri로 요청한 경우 개발자센터에서 생성한 App 정보를 확인하십시오.
unsupported_response_type 요청한 response_type값이 누락되거나 "code"가 아닐경우 "response_type=code"로 지정되어 있는지 확인하십시오.
invalid_scope 요청한 범위가 잘못되었거나 알 수 없거나 형식이 잘못되었습니다. 개발자센터에서 App 생성시 등록한 권한 정보대로 호출했는지 확인하십시오.
access_denied 대표관리자 계정으로 로그인되어있지 않을경우 앱 사용자가 대표 관리자 계정으로 로그인할 수 있도록 안내합니다.

토큰 발급

  • Code를 사용하여 실제로 API를 호출시 필요한 Access Token을 받을 수 있습니다.
  •   - Access Token 발급에 앞서 Code 발급이 반드시 선행되어야 합니다.
  •  
  •  
  • - 토큰 발급 Request 형식 및 샘플
Request 형식

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


Request 샘플

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'

토큰 발급 Request 형식 및 샘플
Key 설명
grant_type "authorization_code" 문자열 값으로 고정합니다.
code 상단의 코드발급에서 획득한 code 입니다.
redirect_uri code 발급시 사용한 동일한 redirect_uri 값입니다.

  •  
  • - 토큰 발급 Response 형식 및 샘플
  • access_token과 해당 토큰의 만료시간, 또한 토큰을 갱신 할 수 있는 refresh_token을 받습니다.
Response 샘플

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"

  }

토큰 발급 Response 형식 및 샘플
Key 설명
access_token API 호출시 필요한 access token 입니다.
expires_at access_token 만료 일시
refresh_token 만료된 access token 재발급을 위해 사용합니다.
client_id 클라이언트 아이디
mall_id 몰 아이디
user_id 사용자 아이디
scopes 사용권한에 동의한 스코프 목록
issued_at 발급 일시

  •  
  • - Error Response 형식 및 샘플
Error Response 샘플

HTTP/1.1 400 Bad Request

{
    "error":"invalid_grant",
    "error_description":"It is a wrong code."
}
Error Response 형식 및 샘플
Key 설명
error OAuth 2.0 권한 부여 프레임워크의 섹션 5.2에 정의된 오류 코드 값입니다.
error_description 오류에 대한 자세한 설명입니다.
Error Response 오류 코드
Error 코드 발생하는 사례 오류 해결 방법
invalid_client client_id, client_secret 값을 누락하여 요청한 경우 헤더에 Authorization 값을 입력하였는지 확인십시오.
invalid_request redirect_uri, code 값을 누락하여 요청한 경우 요청에 누락된 값이 없는지 확인하십시오.
unsupported_grant_type 요청한 grant_type값이 누락되거나 "authorization_code"가 아닐경우 "grant_type=authorization_code"로 지정되어 있는지 확인하십시오.
invalid_grant 잘못된 client_id, client_secret, redirect_uri로 요청한 경우 개발자센터에서 생성한 App 정보를 확인하십시오.
잘못된 code로 요청한 경우 "코드 발급" 에서 발급 받은 인증된 코드가 맞는지 확인하십시오.
만료된 code로 요청한 경우 "코드 발급" 을 참고하여 새로운 코드 발급을 진행하십시오.