인증

MCP 도구 이름 kb_fast_account__session__login

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

등록한 계좌 자격으로 KB국민은행 조회용 연결을 열고 대상 계좌를 확인합니다.

콘솔에서 등록한 KB국민은행 계좌 자격증명(계좌번호·비밀번호)이 필요합니다. 정식 환경은 유료 플랜을 이용 중일 때만 호출할 수 있습니다.
sandbox 환경에서는 실제 KB국민은행에 접속하지 않습니다. 고정된 모의 값이 옵니다.
이 액션은 파라미터가 없습니다. account_link_id 로 지정한 자격증명이 쓰입니다.

Request

변수명	필수	설명
Authorization	Y	API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. 형식 : Basic base64("{client_id}:{client_secret}") [참고] 인증
X-Env-Scope	Y	호출 환경입니다. `sandbox`샌드박스 — 모의 응답 `real_test`데모 — 하루 100 사용 토큰 `production`정식 — 유료 플랜 전용 [참고] 환경
Idempotency-Key	Y	재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. [참고] 재시도
Content-Type	Y	요청 본문 형식입니다. `application/json`고정값 (기본값)
X-Trace-Id	N	추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.

변수명	타입	길이	필수	설명
provider	string	-	Y	호출할 기관입니다. `kb_fast_account`이 API 고정값 (기본값) 예시 : kb_fast_account
action	string	-	Y	호출할 작업입니다. `kb_fast_account.session.login`이 API 고정값 (기본값) 예시 : kb_fast_account.session.login
account_link_id	string	36	조건부	등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. 형식 : UUID v4 [참고] 자격증명 등록
params	object	-	N	작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fields	object	-	N	민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. [참고] 암호화

추가 파라미터가 없습니다. params 는 {} 로 보냅니다.

bash

curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-login-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "kb_fast_account",
  "action": "kb_fast_account.session.login",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

result.data 의 authenticated 로 로그인 성공 여부를, 확인한 대상 계좌를 확인합니다.

순번	변수명	설명
	authenticated	인증 완료 여부
	account_link_id	연동 ID
	session_status	세션 상태 문자열(sandbox 호출이면 SANDBOX 등)
	masked_account_number	마스킹된 계좌번호 - 계좌 조회까지 됐을 때만 옵니다(조건부)

json

{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "kb_fast_account",
    "action": "kb_fast_account.session.login",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}

순번	오류 코드	발생 조건
	PROVIDER_AUTH_FAILED	인증 거부 — KB국민은행이 로그인 자체를 거부했습니다(KB_FAST_ACCOUNT_AUTH_FAILED). retryable=false.
	PROVIDER_AUTH_FAILED	자격 정보 오류 — 등록한 계좌 자격증명으로 인증하지 못했습니다. retryable=false.
	CREDENTIAL_OWNERSHIP_DENIED	자격증명 접근 거부 — 지정한 자격증명이 이 계정 소유가 아닙니다. retryable=false.
	PROVIDER_UPSTREAM_ERROR	기관 응답 오류 — KB국민은행 응답을 해석하지 못했거나 로그인 처리 중 오류가 있었습니다. retryable=false.
	VALIDATION_INVALID_FIELD	계좌 종류 미지원 — 등록된 계좌가 거래내역 조회를 지원하지 않는 종류입니다(KB_FAST_ACCOUNT_ACCOUNT_KIND_UNSUPPORTED). 2026-09-15 2차 검증으로 위치 정정 - 로그인 시퀀스 안에서만 판정되며 transaction_history.search 에서는 나지 않습니다.
	PROVIDER_UNAVAILABLE	그 밖의 오류 — 그 밖의 KB국민은행 오류입니다. retryable 은 원인마다 다릅니다.

인증

1. KB국민은행 빠른조회 계좌 연결 로그인kb_fast_account.session.login

Request

Response