개발 가이드 · 2-Legged · Client Credentials

OAuth2 개발가이드

DJBank Open API를 호출하기 위한 ClientID/Secret 기반 토큰 발급과

Bearer 인증 호출 방법을 단계별로 설명합니다.

Server-to-Server cURL 예제 application/x-www-form
PREREQUISITE

시작 전 준비 사항

1

앱 등록

개발자포털 [내 앱] 메뉴에서 신규

애플리케이션을 등록합니다.

2

ClientID / Secret 발급

승인 완료 후 발급된 자격증명을

서버 환경변수에 안전하게 보관.

3

Scope 확인

호출하려는 API에 필요한 scope

권한이 부여됐는지 확인합니다.

SEQUENCE

전체 인증·호출 시퀀스

Client Application DJBank Open API ① POST /dj/oauth/token grant_type=client_credentials, client_id, client_secret, scope ② access_token 발급 { access_token, token_type:"bearer", expires_in:86400, scope, jti } ③ GET /api/v1/... · X-AUTH-TOKEN: Bearer <access_token> ④ 검증 후 API 응답
STEP 1

액세스 토큰 요청

ClientID/Secret 으로 토큰 엔드포인트에 POST 합니다.

GET · POST https://openapi.djbank.co.kr/dj/oauth/token x-www-form-urlencoded

요청 파라미터

PARAMETER REQ 설명
grant_type 필수 고정값 "client_credentials"
client_id 필수 발급받은 클라이언트 식별자
client_secret 필수 발급받은 비밀 키 (서버 보관)
scope 필수 고정값 "api"

⚠ Content-Type: application/x-www-form-urlencoded 헤더 필수

cURL 
# 액세스 토큰 발급
curl -X POST 'https://openapi.djbank.co.kr/dj/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=YOUR_CLIENT_ID' \
  -d 'client_secret=YOUR_CLIENT_SECRET' \
  -d 'scope=api'

# 응답: 200 OK + JSON
STEP 2

액세스 토큰 응답

정상 발급 시 200 OK 와 함께 다음 JSON 을 반환합니다.

200 OK · JSON 
{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 86399,
  "scope": "api",
  "jti": "f47ac10b-58cc-4372-..."
}

# 응답 본문은 캐싱하여 expires_in 동안 재사용 가능

응답 필드

FIELD TYPE 설명
access_token string Bearer 호출에 사용할 토큰
token_type string 고정값 "bearer"
expires_in int 유효 시간(초). 기본 86400
scope string 부여된 권한 범위 (api)
jti string 토큰 고유 ID (감사/취소용)
STEP 3

발급 토큰으로 API 호출

X-AUTH-TOKEN 헤더에 Bearer 토큰을 실어 보호 자원 API 를 호출합니다.

필수 헤더

X-AUTH-TOKEN: Bearer eyJhbGciOiJSUzI1NiJ9...

토큰 재사용 가이드

  • 동일 토큰은 expires_in(기본 86400초) 동안 재사용
  • 만료 임박 시 재발급 후 교체 (예: TTL의 80% 시점)
  • 매 호출마다 토큰을 새로 발급하지 마세요
  • 401 "Access token expired" 응답 시 재발급 후 재호출
cURL 
# 보호 자원 API 호출
curl -X GET \
  'https://openapi.djbank.co.kr/api/v1/accounts' \
  -H 'X-AUTH-TOKEN: Bearer eyJhbGciOiJSUzI..' \
  -H 'Accept: application/json'

# 응답
HTTP/1.1 200 OK
{ "accounts": [ ... ] }
ERROR CODES

대표 에러 응답

HTTP ERROR CODE 의미 해결 가이드
401 E.GW.AUTH_FAIL client not found (client_id 오류) client_id 확인
401 E.GW.AUTH_FAIL Bad client credentials (client_secret 불일치) client_secret 확인
401 E.GW.AUTH_FAIL Include unacceptable scope (허용되지 않은 scope) scope 를 api 로 설정
401 E.GW.AUTH_FAIL Access token expired (토큰 만료) 토큰 재발급 후 재시도
400 E.GW.AUTH_FAIL Invalid Mandatory Field {grant_type} (누락) grant_type 포함 여부 확인
400 E.GW.AUTH_FAIL Invalid Mandatory Field {client_id} (누락) client_id 포함 여부 확인
400 E.GW.AUTH_FAIL Invalid Mandatory Field {client_secret} (누락) client_secret 포함 여부 확인
400 E.GW.AUTH_FAIL Invalid Mandatory Field {scope} (누락) scope=api 포함 여부 확인
ERROR RESPONSE

에러 응답 예시

자격증명 불일치 시 401 Unauthorized 와 함께 다음 JSON 을 반환합니다.

401 Unauthorized · JSON 
{
  "error": "E.GW.AUTH_FAIL",
  "error_description":
    "Unauthorized. [Bad client credentials(Client Secret is not match)]"
}

# 처리: ClientID·Secret 확인 후 재시도

응답 필드

FIELD TYPE 설명
error string 에러 코드 (예: E.GW.AUTH_FAIL)
error_description string 오류 상세 설명 (사람이 읽을 수 있는 형태)

⚠ error 코드는 게이트웨이 표준 코드 (E.GW.AUTH_FAIL)

EXPLORE

API 목록 보러가기

사용 가능한 DJBank Open API 카탈로그를 확인하세요.

API 목록 →