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

OAuth 2.0 · 2-Legged 구현 가이드

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

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

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

PREREQUISITE

시작 전 준비 사항

앱 등록

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

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

ClientID / Secret 발급

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

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

Scope 확인

호출하려는 API에 필요한 scope

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

SEQUENCE

전체 인증·호출 시퀀스

STEP 1

액세스 토큰 요청

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

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

요청 파라미터

PARAMETER	REQ	설명
`grant_type`	필수	고정값 "client_credentials"
`client_id`	필수	발급받은 클라이언트 식별자
`client_secret`	필수	발급받은 비밀 키 (서버 보관)
`scope`	선택	호출 권한 범위 (공백 구분)

⚠ 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=read.accounts'

# 응답: 200 OK + JSON

STEP 2

액세스 토큰 응답

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

200 OK · JSON

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 86400,
  "scope": "read.accounts",
  "jti": "f47ac10b-58cc-4372-..."
}

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

응답 필드

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

STEP 3

발급 토큰으로 API 호출

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

필수 헤더

토큰 재사용 가이드

동일 토큰은 expires_in(기본 86400초) 동안 재사용
만료 임박 시 재발급 후 교체 (예: TTL의 80% 시점)
매 호출마다 토큰을 새로 발급하지 마세요
권한이 다른 API 는 scope 별로 토큰을 분리 발급

cURL

# 보호 자원 API 호출
curl -X GET \
  'https://openapi.djbank.co.kr/api/v1/accounts' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI..' \
  -H 'Accept: application/json'

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

ERROR CODES

대표 에러 응답

HTTP	ERROR CODE	의미	해결 가이드
400	`invalid_request`	필수 파라미터 누락/형식 오류	grant_type, client_id, client_secret 확인
401	`invalid_client`	자격증명 불일치 / 미승인	ClientID·Secret 재확인, 앱 상태 점검
401	`invalid_token`	만료/위·변조된 토큰	토큰 재발급 후 재시도
403	`insufficient_scope`	scope 권한 부족	필요 scope 추가 신청 후 재발급

ERROR RESPONSE

에러 응답 예시

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

401 Unauthorized · JSON

{
  "error": "invalid_client",
  "error_description":
    "Client authentication failed",
  "status": 401,
  "timestamp": "2026-06-10T11:23:45Z"
}

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

응답 필드

FIELD	TYPE	설명
`error`	string	에러 코드 (예: invalid_client)
`error_description`	string	사람이 읽을 수 있는 설명
`status`	int	HTTP 상태 코드
`timestamp`	string	에러 발생 시각 (ISO 8601)

⚠ error 코드는 RFC 6749 표준 코드 또는 DJBank 확장 코드

EXPLORE

API 목록 보러가기

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

API 목록 →