인증

토큰 발급 · 조회 · 갱신 · 폐기

code 를 access token 으로 바꾸고, 정보를 조회하고, 만료되면 갱신하고, 연결을 끊을 때 폐기합니다.

code → 토큰

POSThttps://api.mallstory.kr/api/oauth/token

본문은 application/x-www-form-urlencoded 입니다. 반드시 서버에서 부릅니다(비밀 키가 실립니다).

이름	형식	설명
`grant_type`필수	string	`authorization_code`
`code`필수	string	인가 응답으로 받은 code
`redirect_uri`필수	string	인가 요청 때와 같은 값
`client_id`필수	string	Client ID
`client_secret`필수	string	비밀 키. `Authorization: Basic` 헤더로 보내도 됩니다
`code_verifier`필수	string	인가 요청 때 만든 PKCE verifier

json200 OK

{
  "access_token": "msat_8Hk2wQ7...",
  "refresh_token": "msrt_Q9p1Zr4...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "shop:read orders:read",
  "shop_unique": "66f1c0a2b3d4e5f601234567"
}

필드	형식	설명
`access_token`	string	API 호출에 쓰는 토큰. 2시간 동안 유효합니다
`refresh_token`	string	새 access token 을 받는 토큰. 14일 동안 유효합니다
`expires_in`	number	access token 남은 시간(초)
`scope`	string	판매자가 실제로 승인한 권한. 요청한 것보다 적을 수 있습니다
`shop_unique`	string	토큰이 묶인 쇼핑몰. REST 경로의 `{shop_unique}` 에 넣습니다

갱신

access token 이 만료되면(401) refresh token 으로 새로 받습니다. 갱신할 때마다 refresh token 도 새것으로 바뀝니다(회전). 응답의 새 refresh token 을 저장하고 이전 것은 버리세요.

bash

curl -X POST 'https://api.mallstory.kr/api/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=refresh_token \
  -d refresh_token=msrt_Q9p1Zr4... \
  -d client_id=ms_xxxxxxxxxxxx \
  -d client_secret=YOUR_CLIENT_SECRET

refresh token 까지 만료(14일)되었거나 판매자가 연결을 끊었다면 invalid_grant 가 옵니다. 판매자에게 다시 인가를 받습니다.

폐기

POSThttps://api.mallstory.kr/api/oauth/revoke

판매자가 외부 서비스에서 연결을 끊을 때 부릅니다(RFC 7009). 토큰은 즉시 무효가 됩니다.

bash

curl -X POST 'https://api.mallstory.kr/api/oauth/revoke' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d token=msrt_Q9p1Zr4... \
  -d client_id=ms_xxxxxxxxxxxx \
  -d client_secret=YOUR_CLIENT_SECRET

토큰 정보 조회

GEThttps://api.mallstory.kr/v1/token

지금 들고 있는 access token 이 어느 앱 · 쇼핑몰에 묶였는지, 어떤 권한인지, 얼마나 남았는지 알려 줍니다. 권한(스코프)이 따로 필요 없습니다. 토큰 값 · refresh token 은 돌려주지 않습니다.

bash

curl 'https://api.mallstory.kr/v1/token' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'

json200 OK

{
  "active": true,
  "token_type": "Bearer",
  "client_id": "ms_5428ce95a009d074134eeb80",
  "app_name": "주문관리 연동",
  "shop_unique": "66f1c0a2b3d4e5f601234567",
  "shop_id": "myshop",
  "scope": "shop:read orders:read",
  "expires_in": 7199,
  "expires_at": "2026-10-12T07:19:12.966Z",
  "issued_at": "2026-10-12T05:19:12.966Z",
  "refresh_expires_in": 1209599
}

필드	형식	설명
`active`	boolean	쓸 수 있는 토큰이면 true. 쓸 수 없으면 401 이 옵니다
`client_id`	string	토큰을 받은 앱의 Client ID
`app_name`	string	토큰을 받은 앱의 이름
`shop_unique`	string	토큰이 묶인 쇼핑몰의 키. REST 경로의 `{shop_unique}` 에 넣습니다
`shop_id`	string	토큰이 묶인 쇼핑몰의 아이디. MCP 주소 `/mcp/{shop_id}` 에 씁니다
`scope`	string	지금 쓸 수 있는 권한(공백 구분). 판매자가 앱 권한을 줄이면 여기서도 바로 줄어듭니다
`expires_in`	number	access token 이 남은 시간(초)
`expires_at`	ISO	access token 이 끝나는 시각(UTC)
`issued_at`	ISO	이 access token 이 나온 시각. 갱신하면 바뀝니다
`refresh_expires_in`	number	refresh token 이 남은 시간(초). 0 에 가까우면 다시 인가를 받을 준비를 합니다

이럴 때 씁니다

저장해 둔 토큰이 아직 살아 있는지 · 어느 쇼핑몰 것인지 확인할 때, 판매자가 권한을 바꾼 뒤 지금 권한을 다시 읽을 때. 401 이면 갱신하거나 다시 인가를 받습니다.

유효 시간

값	유효 시간	비고
authorization code	10분	한 번만 사용. 재사용이 감지되면 그 code 로 발급된 토큰을 모두 폐기합니다
access token	2시간	Bearer 헤더에 싣습니다
refresh token	14일	갱신할 때마다 새것으로 바뀝니다

code → 토큰#

갱신#

폐기#

토큰 정보 조회#

유효 시간#

code → 토큰

갱신

폐기

토큰 정보 조회

유효 시간