인증

MCP 도구 이름 comwel__auth__npki_session__login

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

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

사업자 공동인증서로 근로복지공단 토탈서비스에 로그인해 이후 조회에 쓸 연결을 만듭니다.

콘솔에서 발급한 API 키와 등록한 공동인증서가 필요합니다. 정식 환경은 유료 플랜을 이용 중일 때만 호출할 수 있습니다.
sandbox 환경에서는 실제 근로복지공단에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
사업자등록번호(business_registration_no)는 필수입니다(2026-09-15 정정 - 선택이 아닙니다). 하이픈을 뺀 10자리여야 하며, 빠지거나 자릿수가 다르면 위 자격증명 오류로 실패합니다. 별칭 businessRegistrationNo · business_no · businessNo · saeopja_drno 도 받습니다.

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

순번	변수명	타입	필수	설명
	business_registration_no	string	N	- 별칭 businessRegistrationNo / business_no / businessNo / saeopja_drno / SAEOPJA_DRNO

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": "comwel",
  "action": "comwel.auth.npki_session.login",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

result.data 의 authenticated 로 로그인 성공 여부를, cookie_count 로 확보한 쿠키 수를 확인합니다.

순번	변수명	설명
	success	요청 처리 성공 여부
	API_KEY	연동 ID(account_link_id)
	auth_provider	인증 방식 - 등록한 공동인증서(npki_anysign)
	authenticated	세션 인증 완료 여부
	live_token_material_ready	이후 조회에 쓸 인증 재료 준비 여부
	missing_live_token_keys	누락된 인증 재료 키 목록
	cookie_count	저장된 쿠키 수
	business_registration_no	사업자등록번호
	business_management_no	사업장관리번호
	business_management_no_display	사업장관리번호 - 000-00-00000-0 표기
	generation_status	세션 생성 상태

json

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

순번	오류 코드	발생 조건
	VALIDATION_INVALID_FIELD	자격증명 없음 · 연동 ID 오류 — 콘솔에 공동인증서를 등록하지 않았거나 account_link_id 가 이 조직의 것이 아닙니다. 재시도 불가로 표시되며, 실제로 재시도해도 값을 고치지 않으면 계속 실패합니다.
	PROVIDER_UNAVAILABLE	로그인 실패 — 등록한 인증서의 비밀번호·재료가 잘못됐거나 근로복지공단 접속에 실패했습니다. 재시도 가능으로 표시되지만 인증서 자체가 원인이면 재시도로 해결되지 않으므로 등록한 인증서를 먼저 확인합니다.
	PROVIDER_AUTH_FAILED	세션 저장 실패 — 로그인은 됐지만 세션을 저장하지 못했습니다.

2. 고용산재 세션 상태 조회comwel.auth.session.status

MCP 도구 이름 comwel__auth__session__status

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

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

근로복지공단 연결이 지금도 유효한지와 어느 사업장에 붙어 있는지 확인합니다.

선행 호출이 없어도 됩니다. 로그인 전에 불러도 실패하지 않고 exists:false 로 답합니다. params 는 빈 객체로 보냅니다. [근로복지공단 로그인]
sandbox 에서는 이 액션도 예외 없이 모의 응답입니다(action_router.py:80-81 의 sandbox 분기가 등록된 전 액션에 걸립니다) - exists·authenticated 는 오지 않고 mock: true 와 params_echo 만 옵니다.
params 는 빈 객체로 보내도 호출됩니다.

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	호출할 기관입니다. `comwel`이 API 고정값 (기본값) 예시 : comwel
action	string	-	Y	호출할 작업입니다. `comwel.auth.session.status`이 API 고정값 (기본값) 예시 : comwel.auth.session.status
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-status-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "comwel",
  "action": "comwel.auth.session.status",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

result.data 의 exists · authenticated 로 세션이 있는지, 인증됐는지 확인합니다. 세션이 없어도 Job 은 실패하지 않고 exists: false 로 응답합니다.

순번	변수명	설명
	exists	세션 존재 여부(false 이면 로그인 필요)
	API_KEY	연동 ID(account_link_id)
	authenticated	인증 완료 여부
	live_token_material_ready	이후 조회에 쓸 인증 재료 준비 여부
	missing_live_token_keys	누락된 인증 재료 키 목록
	live_token_keys_present	인증 재료 키별 보유 여부 객체
	cookie_count	저장된 쿠키 수
	business_registration_no	사업자등록번호
	business_management_no	사업장관리번호
	business_management_no_display	사업장관리번호 - 000-00-00000-0 표기
	login_probe	로그인 확인 요청 결과
	flow_source	로그인 출처
	session_key_names	저장된 세션 키 이름 목록

json

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

인증

1. 고용산재 NPKI 세션 로그인comwel.auth.npki_session.login

Request

Response

2. 고용산재 세션 상태 조회comwel.auth.session.status

Request

Response