인증

서버에서 XBOSS API 를 호출할 때 Authorization 헤더를 어떻게 만들어 넣는지 설명합니다.

콘솔 키 관리에서 받은 client_id 와 client_secret 을 콜론(:)으로 이어 Base64 로 인코딩하고, Authorization: Basic {인코딩 값} 형태로 보냅니다. 모든 요청에 같은 헤더를 넣습니다.

STEP 01
키 준비
콘솔에서 발급한 client_id 와 client_secret 을 준비합니다.
STEP 02
콜론으로 잇기
client_id:client_secret 한 줄을 만듭니다.
STEP 03
Base64 인코딩
UTF-8 문자열을 Base64 로 바꿉니다.
STEP 04
헤더에 담기
Authorization: Basic {인코딩 값} 으로 보냅니다.

언어별 예시

terminal

bash

# curl 은 --user 를 주면 Basic 헤더를 대신 만들어 줍니다.
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --user "$XDATA_CLIENT_ID:$XDATA_CLIENT_SECRET" \
  --header 'X-Env-Scope: sandbox' \
  --header "Idempotency-Key: $(uuidgen)" \
  --header 'Content-Type: application/json' \
  --data '{"provider":"hometax","action":"hometax.etax.invoice.search_list","params":{"from_date":"2026-01-01","to_date":"2026-01-31"}}'

submit-job.mjs

javascript

// Node.js 18+
import { randomUUID } from 'node:crypto';

const token = Buffer.from(
  `${process.env.XDATA_CLIENT_ID}:${process.env.XDATA_CLIENT_SECRET}`,
).toString('base64');

const response = await fetch('https://api.xdata.kr/v1/jobs', {
  method: 'POST',
  headers: {
    Authorization: `Basic ${token}`,
    'X-Env-Scope': 'sandbox',
    'Idempotency-Key': randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    provider: 'hometax',
    action: 'hometax.etax.invoice.search_list',
    params: { from_date: '2026-01-01', to_date: '2026-01-31' },
  }),
});

submit_job.py

python

# pip install requests
import base64, os, uuid, requests

token = base64.b64encode(
    f"{os.environ['XDATA_CLIENT_ID']}:{os.environ['XDATA_CLIENT_SECRET']}".encode()
).decode()

response = requests.post(
    'https://api.xdata.kr/v1/jobs',
    headers={
        'Authorization': f'Basic {token}',
        'X-Env-Scope': 'sandbox',
        'Idempotency-Key': str(uuid.uuid4()),
        'Content-Type': 'application/json',
    },
    json={
        'provider': 'hometax',
        'action': 'hometax.etax.invoice.search_list',
        'params': {'from_date': '2026-01-01', 'to_date': '2026-01-31'},
    },
)

인증이 실패할 때

코드	HTTP	원인	확인할 것
AUTH_CREDENTIAL_MISSING	401	Authorization 헤더가 없습니다.	모든 요청에 헤더를 넣었는지 봅니다.
AUTH_CREDENTIAL_INVALID	401	형식이 어긋났거나, client_id 와 client_secret 이 맞지 않거나, 폐기된 키입니다. 서버는 이 셋을 구별해 알려 주지 않습니다.	Basic 뒤 공백 한 칸, 콜론으로 이은 문자열, 줄바꿈 없는 Base64 값인지 봅니다. 값이 맞다면 콘솔 키 관리에서 그 키가 사용 중인지 확인하고, 폐기됐다면 새 키로 바꿉니다.
POLICY_ENV_FORBIDDEN	403	인증은 됐지만 그 키가 쓸 수 없는 환경입니다.	X-Env-Scope 값과 키의 환경을 환경에서 맞춰 봅니다.

REST API 연동은 HTTP Basic 으로 인증합니다. MCP 의 OAuth 액세스 토큰은 AI 앱 연결용이라 서버 연동에는 쓰지 않습니다. 쓰면 403 AUTHZ_FORBIDDEN(reason oauth_token_mcp_only)이 옵니다. AI 앱을 붙이는 MCP 는 인증 방식이 다르니 MCP 개요를 봅니다.

client_secret 은 서버에서만 씁니다. 브라우저·모바일 앱에 넣으면 누구나 꺼내 볼 수 있습니다. 환경 변수나 비밀 저장소에 두고 코드에는 이름만 남깁니다.