주소를 보관하고, 필요할 때만 사용하세요.

시작하는 방법

DEV 플랜 신청 후 Microsoft 계정으로 포털에 로그인하여 구매를 연결합니다. 준비를 신청하고 조직, 계약, Vault, 앱, 권한과 보관 기간을 확인한 뒤 승인과 활성화를 거쳐 더미 데이터로 테스트합니다. 구매만으로 환경이나 데이터 권한이 자동 생성되지는 않습니다. 운영 사용 조건은 별도로 협의합니다.

연결 전 준비 사항

OneNym과 구매 계약, 이용 조직, Vault 테넌트, 판매자·배송 앱 ID, 목적, 허용 필드와 보관 기간을 정합니다. API HTTPS origin, API application ID, directory tenant ID를 받으세요. 웹사이트와 구매 포털은 API 주소가 아닙니다. 구매 후 설정과 승인이 필요합니다.

Microsoft Entra 애플리케이션 Bearer token을 사용합니다. Azure에서는 Managed Identity, 인증서 방식에서는 개인 키로 앱을 인증해 토큰을 받습니다. 통신 경로의 mTLS 인증이 아닙니다. 현재 Vault는 하나의 Entra 디렉터리를 신뢰하며 다른 조직을 자동 지원하지 않습니다. 자격 증명은 백엔드에만 둡니다.

ONENYM_API_URL=<API HTTPS origin>
ONENYM_API_APPLICATION_ID=<API application ID>
directory tenant ID / merchant client ID / carrier client ID

Authorization: Bearer <application-access-token>

로컬 도입 샘플 실행

OneNym에서 SDK 소스와 샘플 패키지를 받아 새 폴더에 풉니다. .NET 10 SDK, PowerShell 7, NuGet 연결이 필요합니다. 아래 명령은 Azure 계정 없이 더미 데이터로 18개 작업을 확인합니다. 로컬 인증·SQLite·키는 데모 전용이며 서비스의 계약·인증을 우회하는 방법이 아닙니다. 동봉 SDK 소스를 사용하며 공개 NuGet 배포를 전제하지 않습니다.

dotnet --version
pwsh --version
pwsh -NoProfile -File ./samples/OneNym.Vault.Pilot/run-local.ps1

RESULT passed=True; steps=18; elapsedMs=…; cleanup=True
PASS isolated customer quickstart

주문부터 배송까지

1. 01 / REGISTER

   인증된 API로 주소를 등록하면 암호화하여 저장하고 예측하기 어려운 대리 ID를 반환합니다. 입력 서버와 로그에 주소 사본이 남지 않도록 연동 경로도 설계합니다.

2. 02 / REFERENCE

   주문 DB에는 주문 번호와 대리 ID를 저장합니다. ID는 주소나 조회 권한이 아닙니다. 기존 사본은 자동 삭제되지 않으므로 이전과 삭제가 필요합니다.

3. 03 / AUTHORIZE

   주문, 대리 ID, 수신 앱, 항목과 만료 시각을 연결하고 사용 횟수가 제한된 토큰을 발급합니다. 토큰 소지만으로는 접근할 수 없습니다.

4. 04 / RETRIEVE

   앱을 인증한 뒤 조직, 주문, 목적, 항목, 만료, 횟수와 계약 상태를 검사합니다. 허용 항목은 평문으로 반환되므로 수신 측 저장과 로그도 관리해야 합니다.

POST /v1/addresses
  → proxyId: nym_…

PUT /v1/shipping-orders
  proxyId + orderReference + recipientClientId + fields + expiresAt
  → orderId + version

POST /v1/shipping-orders/{orderId}/grants
  orderVersion + expiresAt + maxUses
  → token: nrt_…

POST /v1/retrieval-grants/redeem
  Authorization: Bearer <application-access-token>
  X-OneNym-Retrieval-Token: <retrieval-token>
  orderId + orderReference + purpose + fields
  → permitted fields

설계를 설명하는 예시입니다. 필드명과 값은 설명용이며 실행 가능한 API 명세가 아닙니다.

주소 레코드 전체를 메모리에서 복호화한 뒤 허용 필드만 응답합니다. 필드별 암호화는 아닙니다. 수신한 평문과 등록 전 고객 시스템의 로그·저장은 별도로 관리해야 합니다.

API와 SDK 작업

모든 작업에 앱 Bearer token과 권한이 필요합니다. 배송 조회에는 X-OneNym-Retrieval-Token도 필요합니다. UTF-8 JSON과 shipping 목적을 사용합니다. GET·폐기·DELETE에는 본문을 보내지 않습니다. 예제는 인증된 merchant와 carrier, 등록 전에 저장한 persistedKey, 개인정보가 없는 orderReference를 전제합니다. 실행 가능한 앱은 샘플 패키지를 사용하세요.

using OneNym.Vault.Client;

var fields = new[] { "recipientName", "postalCode", "addressLine1" };
var registration = await merchant.RegisterAsync(new CreateAddress {
    Address = new AddressData {
        RecipientName = "Demo Recipient", PostalCode = "000-0000",
        CountryCode = "JP", AddressLine1 = "Dummy address",
        Locality = "Demo city"
    },
    RetainUntil = DateTimeOffset.UtcNow.AddDays(1)
}, persistedKey);

var order = await merchant.BindAsync(new BindOrder(
    orderReference, registration.ProxyId, carrierClientId, fields,
    DateTimeOffset.UtcNow.AddHours(1)));
var grant = await merchant.IssueAsync(
    order.OrderId, order.Version, DateTimeOffset.UtcNow.AddMinutes(5));
var address = await carrier.RedeemAsync(
    order.OrderId, orderReference, grant.Token, fields);

필드·만료·사용 횟수

아래의 주소 필드 7개를 지원합니다. countryCode는 대문자 두 글자이며 JSON 본문은 16,384바이트까지입니다. 초기 최대 보관 기간은 30일이며 배포 설정을 따릅니다. 배송 토큰은 주소·주문 만료 이전이며 발급 후 15분 이내여야 합니다. API maxUses는 1~5, 표준 SDK는 1입니다. UTC 초 단위로 만료 시점부터 접근을 거부합니다. 주소의 실재·배송 가능 여부는 확인하지 않습니다.

recipientName   1–200
postalCode      1–32
countryCode     [A-Z]{2}
addressLine1    1–300
addressLine2    null / 0–300
locality        1–100
region          null / 0–100

주소 정정·주문·폐기

기존 주소를 수정하지 않고 새로 등록합니다. 현재 연결을 조회해 Version을 expectedVersion으로 전달하고 주문을 변경한 뒤 새 버전 토큰을 발급합니다. 버전이 바뀌면 모든 이전 버전 토큰이 차단됩니다. 같은 버전에서 추가 발급해도 기존 토큰은 폐기되지 않습니다. 이전 주소 삭제 전 다른 주문과 보관 의무를 확인하세요. 이미 전달된 평문은 회수할 수 없습니다.

var current = await merchant.InspectOrderAsync(orderReference);
var changed = await merchant.BindAsync(new BindOrder(
    orderReference, newRegistration.ProxyId, carrierClientId, fields,
    newOrderExpiry, ExpectedVersion: current.Version));
var newGrant = await merchant.IssueAsync(
    changed.OrderId, changed.Version, newGrantExpiry);

// BindOrder = complete desired binding, not a partial patch.
// Keep unknown prior outcomes for reconciliation; never blindly retry.

오류와 결과가 불명확한 경우

SDK는 자동 재시도하지 않습니다. 저장 또는 토큰 소비 후에도 시간 초과·취소·503이 발생할 수 있습니다. 실패 응답만으로 미실행이라 판단하지 말고 작업별 결과를 확인합니다.

400 / 413 / 415

입력, JSON 중복·알 수 없는 필드, 자료형과 기한을 확인합니다. 400은 잘못된 입력, 413은 본문 초과, 415는 지원하지 않는 형식입니다. 값을 임의로 바꿔 재전송하지 않습니다.

401 / 403 / 404

인증 대상, audience, 앱 권한, 필드, 목적과 계약을 확인합니다. 404는 다른 소유자의 데이터나 폐기·삭제된 대상도 숨기므로 존재 여부의 증거가 아닙니다.

409

기한·사용 횟수·주문 버전·멱등 키 충돌을 확인합니다. 연결을 다시 조회해 동시 변경을 조정합니다. 자동으로 키를 바꾸거나 새 토큰을 발급하지 않습니다.

429 / Retry-After

설정된 한도에 도달했습니다. Retry-After를 따르고 동시 실행을 줄이며 재실행 가능한 작업인지 판단합니다. 대기 시간이나 처리 능력 보장이 아닙니다.

SDK / 503

SDK 408/timeout_outcome_unknown, 0/transport_unavailable, 502/invalid_response, 취소와 API 503은 결과 불명 상태일 수 있습니다. 등록은 동일한 저장 키·원본 본문·만료 시각으로만 복구합니다. 등록 증표는 최대 24시간 또는 주소 보관 기한 중 이른 시점까지입니다. 주문 binding을 조회하세요. 발급된 원본 토큰은 다시 조회할 수 없으므로 배송 처리 여부 확인 후 재발급·폐기를 결정합니다.

HTTP 상태, 발생 시각, 가능한 경우 trace ID를 알려주세요. 주소 본문, Bearer, 인증서 개인 키, 배송 토큰은 지원팀에 보내지 마세요.

구현·검증 범위

등록, 필드 제한 조회, 버전별 주문 변경, 배송 토큰 발급·횟수 제한·폐기, 삭제·기한 정리를 구현했습니다. SDK·격리 SQL·실제 Azure MI·Key Vault·Azure SQL·이력 저장으로 정상 처리, 권한 거부, 경쟁과 장애 복구를 확인했습니다. 별도 조직의 실제 구매·동의 및 Microsoft 실제 중지·재개 알림은 남은 수용 검증입니다. 본 검증은 운영 SLA나 모든 구성의 성능 보장이 아닙니다.

FAQ

관련 기술 설계