OAuth2 가이드 문서 업데이트:
- 인증 헤더 `X-AUTH-TOKEN`으로 변경 - `scope` 필수값 "api"로 수정 - 오류 코드 및 설명 표준화 (`E.GW.AUTH_FAIL`)
This commit is contained in:
Rinjae
@@ -123,7 +123,7 @@
|
||||
<line x1="880" y1="170" x2="240" y2="170" stroke="#64748B" stroke-width="2" marker-end="url(#o2leg-arrow-gray)"/>
|
||||
<text x="560" y="188" text-anchor="middle" font-size="11" font-weight="500" fill="#64748B">{ access_token, token_type:"bearer", expires_in:86400, scope, jti }</text>
|
||||
|
||||
<text x="560" y="216" text-anchor="middle" font-size="12" font-weight="700" fill="#0049b4">③ GET /api/v1/... · Authorization: Bearer <access_token></text>
|
||||
<text x="560" y="216" text-anchor="middle" font-size="12" font-weight="700" fill="#0049b4">③ GET /api/v1/... · X-AUTH-TOKEN: Bearer <access_token></text>
|
||||
<line x1="240" y1="226" x2="880" y2="226" stroke="#0049b4" stroke-width="2" marker-end="url(#o2leg-arrow-primary)"/>
|
||||
|
||||
<text x="560" y="248" text-anchor="middle" font-size="12" font-weight="700" fill="#64748B">④ 검증 후 API 응답</text>
|
||||
@@ -139,7 +139,7 @@
|
||||
<p class="oauth2-2legged__desc">ClientID/Secret 으로 토큰 엔드포인트에 POST 합니다.</p>
|
||||
|
||||
<div class="oauth2-2legged__endpoint-box">
|
||||
<span class="oauth2-2legged__method">POST</span>
|
||||
<span class="oauth2-2legged__method">GET · POST</span>
|
||||
<code class="oauth2-2legged__endpoint-path">https://openapi.djbank.co.kr/dj/oauth/token</code>
|
||||
<span class="oauth2-2legged__endpoint-content-type">x-www-form-urlencoded</span>
|
||||
</div>
|
||||
@@ -173,8 +173,8 @@
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>scope</code></td>
|
||||
<td><span class="oauth2-2legged__req-badge oauth2-2legged__req-badge--optional">선택</span></td>
|
||||
<td>호출 권한 범위 (공백 구분)</td>
|
||||
<td><span class="oauth2-2legged__req-badge oauth2-2legged__req-badge--required">필수</span></td>
|
||||
<td>고정값 "api"</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
@@ -189,7 +189,7 @@ curl -X <span class="o2leg-y">POST</span> <span class="o2leg-c">'https://openapi
|
||||
-d <span class="o2leg-c">'grant_type=client_credentials'</span> \
|
||||
-d <span class="o2leg-c">'client_id=YOUR_CLIENT_ID'</span> \
|
||||
-d <span class="o2leg-c">'client_secret=YOUR_CLIENT_SECRET'</span> \
|
||||
-d <span class="o2leg-c">'scope=read.accounts'</span>
|
||||
-d <span class="o2leg-c">'scope=api'</span>
|
||||
|
||||
<span class="o2leg-g"># 응답: 200 OK + JSON</span></pre>
|
||||
</div>
|
||||
@@ -208,8 +208,8 @@ curl -X <span class="o2leg-y">POST</span> <span class="o2leg-c">'https://openapi
|
||||
<pre class="oauth2-2legged__code-block">{
|
||||
<span class="o2leg-c">"access_token"</span>: <span class="o2leg-y">"eyJhbGciOiJSUzI1NiJ9..."</span>,
|
||||
<span class="o2leg-c">"token_type"</span>: <span class="o2leg-y">"bearer"</span>,
|
||||
<span class="o2leg-c">"expires_in"</span>: <span class="o2leg-p">86400</span>,
|
||||
<span class="o2leg-c">"scope"</span>: <span class="o2leg-y">"read.accounts"</span>,
|
||||
<span class="o2leg-c">"expires_in"</span>: <span class="o2leg-p">86399</span>,
|
||||
<span class="o2leg-c">"scope"</span>: <span class="o2leg-y">"api"</span>,
|
||||
<span class="o2leg-c">"jti"</span>: <span class="o2leg-y">"f47ac10b-58cc-4372-..."</span>
|
||||
}
|
||||
|
||||
@@ -245,7 +245,7 @@ curl -X <span class="o2leg-y">POST</span> <span class="o2leg-c">'https://openapi
|
||||
<tr>
|
||||
<td><code class="oauth2-2legged__field-name">scope</code></td>
|
||||
<td>string</td>
|
||||
<td>실제 부여된 권한 범위</td>
|
||||
<td>부여된 권한 범위 (api)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code class="oauth2-2legged__field-name">jti</code></td>
|
||||
@@ -262,13 +262,13 @@ curl -X <span class="o2leg-y">POST</span> <span class="o2leg-c">'https://openapi
|
||||
<section class="oauth2-2legged__step" aria-labelledby="o2leg-step3-title">
|
||||
<span class="oauth2-2legged__eyebrow">STEP 3</span>
|
||||
<h2 class="oauth2-2legged__h2" id="o2leg-step3-title">발급 토큰으로 API 호출</h2>
|
||||
<p class="oauth2-2legged__desc">Authorization 헤더에 Bearer 토큰을 실어 보호 자원 API 를 호출합니다.</p>
|
||||
<p class="oauth2-2legged__desc">X-AUTH-TOKEN 헤더에 Bearer 토큰을 실어 보호 자원 API 를 호출합니다.</p>
|
||||
|
||||
<div class="oauth2-2legged__step-grid">
|
||||
<div class="oauth2-2legged__panel">
|
||||
<h3 class="oauth2-2legged__panel-title">필수 헤더</h3>
|
||||
<div class="oauth2-2legged__header-box">
|
||||
<code class="oauth2-2legged__header-key">Authorization:</code>
|
||||
<code class="oauth2-2legged__header-key">X-AUTH-TOKEN:</code>
|
||||
<code class="oauth2-2legged__header-value">Bearer eyJhbGciOiJSUzI1NiJ9...</code>
|
||||
</div>
|
||||
|
||||
@@ -277,7 +277,7 @@ curl -X <span class="o2leg-y">POST</span> <span class="o2leg-c">'https://openapi
|
||||
<li>동일 토큰은 expires_in(기본 86400초) 동안 재사용</li>
|
||||
<li>만료 임박 시 재발급 후 교체 (예: TTL의 80% 시점)</li>
|
||||
<li>매 호출마다 토큰을 새로 발급하지 마세요</li>
|
||||
<li>권한이 다른 API 는 scope 별로 토큰을 분리 발급</li>
|
||||
<li>401 "Access token expired" 응답 시 재발급 후 재호출</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
@@ -286,7 +286,7 @@ curl -X <span class="o2leg-y">POST</span> <span class="o2leg-c">'https://openapi
|
||||
<pre class="oauth2-2legged__code-block"><span class="o2leg-cm"># 보호 자원 API 호출</span>
|
||||
curl -X <span class="o2leg-y">GET</span> \
|
||||
<span class="o2leg-c">'https://openapi.djbank.co.kr/api/v1/accounts'</span> \
|
||||
-H <span class="o2leg-c">'Authorization: Bearer eyJhbGciOiJSUzI..'</span> \
|
||||
-H <span class="o2leg-c">'X-AUTH-TOKEN: Bearer eyJhbGciOiJSUzI..'</span> \
|
||||
-H <span class="o2leg-c">'Accept: application/json'</span>
|
||||
|
||||
<span class="o2leg-g"># 응답</span>
|
||||
@@ -313,28 +313,52 @@ HTTP/1.1 <span class="o2leg-g">200 OK</span>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><span class="oauth2-2legged__status-badge oauth2-2legged__status-badge--400">400</span></td>
|
||||
<td><code>invalid_request</code></td>
|
||||
<td>필수 파라미터 누락/형식 오류</td>
|
||||
<td>grant_type, client_id, client_secret 확인</td>
|
||||
<td><span class="oauth2-2legged__status-badge oauth2-2legged__status-badge--400">401</span></td>
|
||||
<td><code>E.GW.AUTH_FAIL</code></td>
|
||||
<td>client not found (client_id 오류)</td>
|
||||
<td>client_id 확인</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><span class="oauth2-2legged__status-badge oauth2-2legged__status-badge--400">401</span></td>
|
||||
<td><code>invalid_client</code></td>
|
||||
<td>자격증명 불일치 / 미승인</td>
|
||||
<td>ClientID·Secret 재확인, 앱 상태 점검</td>
|
||||
<td><code>E.GW.AUTH_FAIL</code></td>
|
||||
<td>Bad client credentials (client_secret 불일치)</td>
|
||||
<td>client_secret 확인</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><span class="oauth2-2legged__status-badge oauth2-2legged__status-badge--400">401</span></td>
|
||||
<td><code>invalid_token</code></td>
|
||||
<td>만료/위·변조된 토큰</td>
|
||||
<td><code>E.GW.AUTH_FAIL</code></td>
|
||||
<td>Include unacceptable scope (허용되지 않은 scope)</td>
|
||||
<td>scope 를 api 로 설정</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><span class="oauth2-2legged__status-badge oauth2-2legged__status-badge--400">401</span></td>
|
||||
<td><code>E.GW.AUTH_FAIL</code></td>
|
||||
<td>Access token expired (토큰 만료)</td>
|
||||
<td>토큰 재발급 후 재시도</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><span class="oauth2-2legged__status-badge oauth2-2legged__status-badge--403">403</span></td>
|
||||
<td><code>insufficient_scope</code></td>
|
||||
<td>scope 권한 부족</td>
|
||||
<td>필요 scope 추가 신청 후 재발급</td>
|
||||
<td><span class="oauth2-2legged__status-badge oauth2-2legged__status-badge--403">400</span></td>
|
||||
<td><code>E.GW.AUTH_FAIL</code></td>
|
||||
<td>Invalid Mandatory Field {grant_type} (누락)</td>
|
||||
<td>grant_type 포함 여부 확인</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><span class="oauth2-2legged__status-badge oauth2-2legged__status-badge--403">400</span></td>
|
||||
<td><code>E.GW.AUTH_FAIL</code></td>
|
||||
<td>Invalid Mandatory Field {client_id} (누락)</td>
|
||||
<td>client_id 포함 여부 확인</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><span class="oauth2-2legged__status-badge oauth2-2legged__status-badge--403">400</span></td>
|
||||
<td><code>E.GW.AUTH_FAIL</code></td>
|
||||
<td>Invalid Mandatory Field {client_secret} (누락)</td>
|
||||
<td>client_secret 포함 여부 확인</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><span class="oauth2-2legged__status-badge oauth2-2legged__status-badge--403">400</span></td>
|
||||
<td><code>E.GW.AUTH_FAIL</code></td>
|
||||
<td>Invalid Mandatory Field {scope} (누락)</td>
|
||||
<td>scope=api 포함 여부 확인</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
@@ -351,11 +375,9 @@ HTTP/1.1 <span class="o2leg-g">200 OK</span>
|
||||
<div class="oauth2-2legged__code-panel oauth2-2legged__code-panel--error">
|
||||
<span class="oauth2-2legged__code-tag oauth2-2legged__code-tag--error">401 Unauthorized · JSON</span>
|
||||
<pre class="oauth2-2legged__code-block">{
|
||||
<span class="o2leg-c">"error"</span>: <span class="o2leg-y">"invalid_client"</span>,
|
||||
<span class="o2leg-c">"error"</span>: <span class="o2leg-y">"E.GW.AUTH_FAIL"</span>,
|
||||
<span class="o2leg-c">"error_description"</span>:
|
||||
<span class="o2leg-y">"Client authentication failed"</span>,
|
||||
<span class="o2leg-c">"status"</span>: <span class="o2leg-p">401</span>,
|
||||
<span class="o2leg-c">"timestamp"</span>: <span class="o2leg-y">"2026-06-10T11:23:45Z"</span>
|
||||
<span class="o2leg-y">"Unauthorized. [Bad client credentials(Client Secret is not match)]"</span>
|
||||
}
|
||||
|
||||
<span class="o2leg-g"># 처리: ClientID·Secret 확인 후 재시도</span></pre>
|
||||
@@ -375,26 +397,16 @@ HTTP/1.1 <span class="o2leg-g">200 OK</span>
|
||||
<tr>
|
||||
<td><code class="oauth2-2legged__field-name">error</code></td>
|
||||
<td>string</td>
|
||||
<td>에러 코드 (예: invalid_client)</td>
|
||||
<td>에러 코드 (예: E.GW.AUTH_FAIL)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code class="oauth2-2legged__field-name">error_description</code></td>
|
||||
<td>string</td>
|
||||
<td>사람이 읽을 수 있는 설명</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code class="oauth2-2legged__field-name">status</code></td>
|
||||
<td>int</td>
|
||||
<td>HTTP 상태 코드</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code class="oauth2-2legged__field-name">timestamp</code></td>
|
||||
<td>string</td>
|
||||
<td>에러 발생 시각 (ISO 8601)</td>
|
||||
<td>오류 상세 설명 (사람이 읽을 수 있는 형태)</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p class="oauth2-2legged__error-note">⚠ error 코드는 RFC 6749 표준 코드 또는 DJBank 확장 코드</p>
|
||||
<p class="oauth2-2legged__error-note">⚠ error 코드는 게이트웨이 표준 코드 (E.GW.AUTH_FAIL)</p>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
Reference in New Issue
Block a user