인증
1. 고용24 공동인증서 세션 로그인work24.
MCP 도구 이름 work24__auth__npki_session__login
POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox
샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.
사업자 공동인증서로 고용24에 로그인해 이후 지원금 업무에 쓸 연결을 만듭니다.
- 콘솔에서 발급한 API 키와 등록한 공동인증서가 필요합니다. 정식 환경은 유료 플랜을 이용 중일 때만 호출할 수 있습니다.
- sandbox 환경에서는 실제 고용24에 접속하지 않습니다. result.data 에는 mock: true 와 보낸 params 를 그대로 담은 params_echo 가 오고, 업무 응답 필드는 오지 않습니다.
- 사업자등록번호(business_registration_no)·사업장관리번호(business_management_no)·고유식별번호(isoa_no)·회원구분(member_type_code)은 모두 선택입니다. 생략하면 대표로 지정한 자격증명이 선택됩니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. | |
| params | object | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| business_ | string | N | 11-digit 고용보험 사업장관리번호. Required for 장려금 신청 screens | |
| business_ | string | N | - | |
| isoa_ | string | N | 사무대행기관 번호. Required only when member_type_code=BE902 | |
| member_ | string | N | 회원유형: BE904 일반사업자 (default) or BE902 사무대행기관 |
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": "work24",
"action": "work24.auth.npki_session.login",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- result.data 의 authenticated 로 로그인 성공 여부를, cookie_count 로 확보한 쿠키 수를 확인합니다.
| 순번 | 변수명 | 설명 |
|---|---|---|
| success | 요청 처리 성공 여부 | |
| API_ | 연동 ID(account_link_id) | |
| auth_ | 인증 방식 - 등록한 공동인증서(npki_cms, 2026-09-15 정정 - 예전에는 입력 별칭 npki_anysign 을 잘못 응답값으로 적었습니다) | |
| authenticated | 세션 인증 완료 여부 | |
| live_ | 이후 조회에 쓸 인증 재료 준비 여부 | |
| missing_ | 누락된 인증 재료 키 목록 | |
| cookie_ | 저장된 쿠키 수 | |
| business_ | 사업자등록번호 | |
| business_ | 사업장관리번호 | |
| business_ | 사업장관리번호 - 000-00-00000-0 표기 | |
| member_ | 고용24 회원 구분 코드 | |
| generation_ | 세션 생성 상태 |
json
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "sandbox",
"provider": "work24",
"action": "work24.auth.npki_session.login",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 로그인 실패 — 등록된 공동인증서를 찾지 못했거나, 고용24에 가입돼 있지 않거나, 접속에 실패했습니다. 재시도 가능으로 표시되지만 인증서·가입 상태가 원인이면 재시도로 해결되지 않으므로 그 상태부터 확인합니다. | |
| PROVIDER_ | 세션 저장 실패 — 로그인은 됐지만 세션을 저장하지 못했습니다. |
2. 고용24 세션 상태 조회work24.
MCP 도구 이름 work24__auth__session__status
POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox
샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.
고용24 연결이 유효한지 확인합니다.
- 콘솔에서 발급한 API 키만 있으면 호출됩니다. 세션이 없어도 오류가 아니라 exists:false 로 답합니다. [고용24 로그인]
- sandbox 에서는 이 액션도 예외 없이 모의 응답입니다(action_router.py:80-83 의 sandbox 분기가 등록된 전 액션에 걸립니다) - exists·authenticated 는 오지 않고 mock: true 와 params_echo 만 옵니다.
- params 는 빈 객체로 보내도 호출됩니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다. | |
| params | object | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | 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": "work24",
"action": "work24.auth.session.status",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- result.data 의 exists · authenticated 로 세션이 있는지, 인증됐는지 확인합니다. 세션이 없어도 Job 은 실패하지 않고 exists: false 로 응답합니다.
| 순번 | 변수명 | 설명 |
|---|---|---|
| exists | 세션 존재 여부(false 이면 로그인 필요) | |
| API_ | 연동 ID(account_link_id) | |
| authenticated | 인증 완료 여부 | |
| live_ | 이후 조회에 쓸 인증 재료 준비 여부 | |
| missing_ | 누락된 인증 재료 키 목록 | |
| live_ | 인증 재료 키별 보유 여부 객체 | |
| cookie_ | 저장된 쿠키 수 | |
| business_ | 사업자등록번호 | |
| business_ | 사업장관리번호 | |
| business_ | 사업장관리번호 - 000-00-00000-0 표기 | |
| member_ | 고용24 회원 구분 코드 | |
| login_ | 로그인 확인 요청 결과 | |
| flow_ | 로그인 출처 | |
| session_ | 저장된 세션 키 이름 목록 |
json
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "sandbox",
"provider": "work24",
"action": "work24.auth.session.status",
"submitted_at": "2026-05-27T12:34:56+09:00"
}