개발자 문서
API 레퍼런스

인증 - 고용24

1. 고용24 공동인증서 세션 로그인work24.auth.npki_session.login

MCP 도구 이름 work24__auth__npki_session__login

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

사업자 공동인증서로 고용24에 로그인해 이후 지원금 업무에 쓸 연결을 만듭니다.

  • 콘솔에서 발급한 API 키와 등록한 공동인증서가 필요합니다. 정식 환경은 라이트, 스탠다드, PRO 또는 멀티계정 요금제를 이용 중일 때만 호출할 수 있습니다.
  • 사업자등록번호(business_registration_no)는 필수이고 숫자 10자리입니다(하이픈을 넣어 보내도 숫자만 남겨 씁니다).

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • work24이 API 고정값 (기본값)

예시 : work24

actionstring-Y호출할 작업입니다.
  • work24.auth.npki_session.login이 API 고정값 (기본값)

예시 : work24.auth.npki_session.login

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입필수설명
business_management_nostringN11자리 고용보험 사업장관리번호입니다. 장려금 신청 화면에서 필요합니다
business_registration_nostringY숫자 10자리입니다. 하이픈을 넣어 보내도 숫자만 남겨 씁니다
isoa_nostringN사무대행기관 번호입니다. 회원 유형이 BE902 일 때만 필요합니다
member_type_codestringN회원 유형입니다. BE904 는 일반사업자(기본값), BE902 는 사무대행기관입니다
  • 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: real_test' \
  --header "Idempotency-Key: login-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "work24",
  "action": "work24.auth.npki_session.login",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "business_registration_no": "<필수>"
  }
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • result.data 의 authenticated 로 로그인 성공 여부를, cookie_count 로 확보한 쿠키 수를 확인합니다.
순번변수명타입설명
successboolean요청 처리 성공 여부
API_KEYstring이 호출에 쓴 연동 계정의 ID(account_link_id)입니다. XBOSS API 키가 아닙니다.
auth_providerstring인증 방식 - 등록한 공동인증서(npki_cms)
authenticatedboolean세션 인증 완료 여부
live_token_material_readyboolean이후 조회에 쓸 인증 재료 준비 여부
missing_live_token_keysarray누락된 인증 재료 키 목록
cookie_countnumber저장된 쿠키 수
business_registration_nostring사업자등록번호
business_management_nostring사업장관리번호
business_management_no_displaystring사업장관리번호 - 000000-0000-0 표기(11자리가 아니면 숫자 그대로)
member_type_codestring고용24 회원 구분 코드
generation_statusstring세션 생성 상태
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "work24",
    "action": "work24.auth.npki_session.login",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
PROVIDER_AUTH_FAILED로그인 인증 실패 — 고용24가 로그인을 받아들이지 않았거나, 고용24 기업회원으로 가입돼 있지 않거나, 등록한 인증서를 고용24 로그인에 쓸 수 없습니다. 가입이나 인증서가 원인이면 error.message 가 할 일을 알려 줍니다. 그 밖에는 error.message 안내대로 등록한 인증서와 사업자 정보(사업자등록번호, 회원구분)가 맞는지 확인합니다. 같은 값으로는 다시 호출해도 결과가 같아 재시도 불가로 표시됩니다.
PROVIDER_UNAVAILABLE로그인 실패 — 그 밖의 이유로 고용24 로그인을 마치지 못했습니다. 재시도 가능으로 표시되니 잠시 후 다시 호출하고, 계속되면 서비스문의로 알립니다.
VALIDATION_INVALID_FIELD입력값 오류 — 사업자등록번호(business_registration_no)가 없거나 숫자 10자리가 아니거나, 회원구분(member_type_code)이 BE904 나 BE902 가 아니거나, 등록한 인증서의 비밀번호가 비어 있습니다. 어느 값을 고칠지는 error.message 에 한국어 문장으로 옵니다. 재시도 불가로 표시됩니다.
PROVIDER_UNAVAILABLE기관 연결 실패 — 고용24에 연결하지 못해 로그인 요청을 보내지 못했습니다. error.provider_error_ref 는 work24.connection_error 입니다. 재시도 가능으로 표시되니 잠시 후 다시 호출합니다.
PROVIDER_TIMEOUT_CONNECT연결 지연 — 고용24 접속 자체가 시간 안에 되지 않았습니다. 재시도 가능으로 표시되니 잠시 후 다시 호출합니다.
PROVIDER_TIMEOUT_READ응답 지연 — 로그인 요청은 보냈지만 고용24의 응답이 시간 안에 오지 않았습니다. 재시도 가능으로 표시되니 잠시 후 다시 호출합니다.
PROVIDER_UPSTREAM_ERROR기관 일시 오류 — 고용24가 서버 오류(500 번대) 상태로 답했습니다. error.provider_error_ref 끝의 숫자가 그 상태 코드입니다(예: work24.upstream_http_503). 재시도 가능으로 표시되니 잠시 후 다시 호출합니다.
PROVIDER_VALIDATION_ERROR기관 요청 거절 — 고용24가 로그인 요청을 400 번대 오류 상태로 거절했습니다(403 과 429 는 「접근 제한」 행입니다). 재시도 불가로 표시되니 사업자등록번호와 등록한 인증서를 확인하고, 계속되면 서비스문의로 알립니다.
PROVIDER_IP_REJECTED접근 제한 — 고용24가 접근을 제한했습니다(403 이나 429 상태로 답했거나 접속을 끊음). 재시도 가능으로 표시되니 잠시 후 다시 호출하고, 계속되면 서비스문의로 알립니다.
POLICY_FEATURE_DISABLED개인사업자 — 사업자등록번호가 개인사업자 번호이면 로그인 세션을 저장하지 않고 멈춥니다. error.message 는 「지금은 법인 사업자만 이용할 수 있습니다. 개인사업자는 서비스 안정화 뒤에 열 예정입니다.」 입니다. 재시도 불가로 표시되며, 다시 보내도 같은 답입니다.
PROVIDER_UNAVAILABLE세션 저장 실패 — 로그인은 됐지만 세션을 저장하지 못했습니다. 재시도 가능으로 표시되니 error.message 안내대로 잠시 후 다시 호출합니다.

2. 고용24 세션 상태 조회work24.auth.session.status

MCP 도구 이름 work24__auth__session__status

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

현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.

저장된 고용24 연결의 인증 상태와 회원구분을 확인합니다.

  • 콘솔에서 발급한 API 키만 있으면 호출됩니다. 세션이 없어도 오류가 아니라 exists:false 로 답합니다. [고용24 로그인]
  • params 는 빈 객체로 보내도 호출됩니다.

Request

순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • real_test데모 — 현재 데모 한도 확인 필요
  • production정식 — 현재 공개 요금제 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • work24이 API 고정값 (기본값)

예시 : work24

actionstring-Y호출할 작업입니다.
  • work24.auth.session.status이 API 고정값 (기본값)

예시 : work24.auth.session.status

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-N작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다.
encrypted_fieldsobject-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: real_test' \
  --header "Idempotency-Key: status-$(date +%s)-$RANDOM" \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "work24",
  "action": "work24.auth.session.status",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'

Response

  • 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
  • result.data 의 exists · authenticated 로 세션이 있는지, 인증됐는지 확인합니다. 세션이 없어도 작업은 실패하지 않고 exists: false 로 응답합니다.
순번변수명타입설명
existsboolean세션 존재 여부(false 이면 로그인 필요)
API_KEYstring이 호출에 쓴 연동 계정의 ID(account_link_id)입니다. XBOSS API 키가 아닙니다.
authenticatedboolean인증 완료 여부
live_token_material_readyboolean이후 조회에 쓸 인증 재료 준비 여부
missing_live_token_keysarray누락된 인증 재료 키 목록
cookie_countnumber저장된 쿠키 수
business_registration_nostring사업자등록번호
business_management_nostring사업장관리번호
business_management_no_displaystring사업장관리번호 - 000000-0000-0 표기(11자리가 아니면 숫자 그대로)
member_type_codestring고용24 회원 구분 코드
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "real_test",
    "provider": "work24",
    "action": "work24.auth.session.status",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}