---
title: "고객용 조회 요청 작성하기"
description: "실제 Sandbox가 준비되는 경우 인증, 처리 목적과 데이터 범위를 지키며 조회할 최소 계약 형식입니다."
updated: "2026년 8월 27일"
availability: "REFERENCE RESPONSE"
candidate_route: "/ko/docs/api/quickstart"
---

# 고객용 조회 요청 작성하기

실제 Sandbox가 준비되는 경우 인증, 처리 목적과 데이터 범위를 지키며 조회할 최소 계약 형식입니다.

**REFERENCE RESPONSE:** 요청·응답 계약 검토용 · 실제 Sandbox 준비 후에만 실행 가능

## 먼저 승인된 환경과 자격증명이 필요합니다

- 고객 조직에 배정된 environment ID
- 승인된 사용자에게 전달된 단기 자격증명
- 계약에 포함된 처리 목적과 데이터 범위
- 조직의 비밀정보 저장·회수 기준을 따르는 실행 환경

> **접근 경계:** 이 문서의 예제에는 실제 환경 ID나 토큰이 없습니다. 공개 문서만으로 Sandbox를 호출할 수 없습니다.

## 비밀정보는 코드와 셸 기록에 남기지 않습니다

예시는 설명을 위한 환경변수 이름만 사용합니다. 이 후보에는 실제 호스트를 공개하지 않습니다. 향후 환경을 승인·발급한 경우에만 정확한 좌표와 자격증명을 조직이 승인한 secret manager 또는 별도로 합의한 보안 채널에서 주입합니다.

**환경 좌표**

```bash
export HARBINGER_BASE_URL='https://<issued-environment-host>'
export HARBINGER_SUBJECT_ID='<approved-subject-id>'
export HARBINGER_DATA_PURPOSE='<approved-purpose>'
# HARBINGER_PREVIEW_TOKEN은 승인된 secret manager에서 주입
```

## 승인된 대상의 변화 기록을 조회합니다

실제 `HARBINGER_DATA_PURPOSE`와 `HARBINGER_SUBJECT_ID`는 주문서와 조직별 승인 범위에서 함께 발급합니다. 금융 예제의 목적을 공급망 대상에 재사용하는 것처럼 도메인 결박이 맞지 않는 요청은 거부됩니다.

정상 응답에는 요청 ID, 데이터셋 시점, 조직, 처리 목적, authority 상태와 근거 관측 ID가 포함됩니다. `fact`, `decision`, `execution` authority는 모두 `NONE`입니다.

**GET /changes**

```bash
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer ${HARBINGER_PREVIEW_TOKEN}" \
  -H "Harbinger-Data-Purpose: ${HARBINGER_DATA_PURPOSE}" \
  "${HARBINGER_BASE_URL}/v1/subjects/${HARBINGER_SUBJECT_ID}/changes"
```

## 허용되지 않은 요청은 명시적으로 거부됩니다

- 401 — 자격증명이 없거나 유효하지 않음
- 400 — 처리 목적 헤더가 없음
- 403 — 목적, 기능 또는 대상 데이터 범위를 승인받지 않음
- 405 — READ_ONLY가 아닌 메서드 사용
- 404 — 제공하지 않는 추천·승인·명령·실행 경로 또는 존재하지 않는 리소스

---

공개 경로: /ko/docs/api/quickstart