Cryptanio
계정

API 키의 접근을 하나의 프로젝트로 제한하는 방법

한 프로젝트의 인보이스를 서버에서 확인할 전용 키를 만드세요. 프로젝트, 읽기 권한, 필요한 API 섹션을 선택하고 IP와 만료일을 설정한 뒤 접근 제한을 검증합니다.

수정일:

API 키는 하나의 Cryptanio 프로젝트에 연결할 수 있습니다. 온라인 상점의 인보이스를 읽되 같은 계정의 다른 프로젝트 데이터에는 접근하지 않아야 하는 주문 확인 프로세스를 예로 들겠습니다. 이 프로세스에는 별도의 키가 필요합니다. 프로젝트 연결은 데이터의 범위를 정하고, 권한과 API 섹션은 허용되는 작업을 정합니다.

키 이름이나 애플리케이션에 적힌 프로젝트 번호만으로는 접근이 제한되지 않습니다. 제한 사항을 키의 정책에 저장해야 합니다. 이 접근 권한은 공개 API v1에 적용되며, 키는 계정 화면에 로그인하는 비밀번호가 아닙니다.

1. 프로젝트와 권한 준비하기

계정 소유자 또는 관리자 권한과 «결제» 서비스를 사용하는 기존 활성 프로젝트가 필요합니다. 먼저 프로젝트의 이름과 용도를 정확히 파악하고 있는지 확인하세요. 프로젝트를 잘못 선택하면 유효한 키이더라도 접근 범위가 의도와 달라질 수 있습니다.

«API 키»를 여세요. «API 키 만들기» 양식의 «라벨»에 이름을 입력합니다. 예를 들어 «상점 주문 확인»으로 지정할 수 있습니다. 별도의 이름을 붙이면 서버 프로세스를 구분하기 쉽지만, 실제 보호는 다음 필드에서 설정합니다.

2. 모드와 특정 프로젝트 선택하기

실제 인보이스를 읽으려면 «모드» 필드에서 «라이브»를 선택하세요. 키의 모드는 서버가 요청하는 데이터의 모드와 일치해야 합니다.

«프로젝트» 필드에서 «모든 프로젝트» 대신 필요한 프로젝트를 선택하세요. 계정 화면에는 선택한 프로젝트의 서비스로 접근이 제한된다는 안내가 표시됩니다. 프로젝트 연결과 서비스 접근 권한은 함께 적용됩니다. 키 자체가 서비스를 활성화하거나 서비스의 기능을 확장하지는 않습니다.

3. 인보이스 읽기만 허용하기

접근 권한을 지정하는 «오시는 길» 필드에서 «만 읽으십시오»를 선택하세요. «API 섹션»에서는 «인보이스»를 남기고, 프로세스에 필요하지 않은 나머지 항목의 선택을 해제합니다. 일반적인 인보이스 상태 확인에는 주소, webhook, 시뮬레이션 관리 권한이 필요하지 않습니다.

다른 서버가 인보이스를 생성해야 한다면 해당 섹션과 «읽기 및 쓰기» 권한이 필요합니다. 주문 확인 프로세스의 권한을 불필요하게 늘리지 말고, 목적이 명확한 별도 키를 발급하세요. 쓰기 권한은 선택한 섹션 안에서만 적용되며 API 전체를 개방하지 않습니다.

4. IP와 만료일 설정하기

«IP 주소 허용»에 서버의 공인 출구 IP 또는 필요한 CIDR 범위를 한 줄에 하나씩 입력하세요. 필요한 것은 구매자의 IP가 아니라 요청이 API에 도달할 때 사용하는 출발지 주소입니다. 호스팅이나 프록시를 사용하는 경우 실제 출구 주소를 확인하세요.

필드를 비워 두면 모든 IP가 허용됩니다. 서버가 여러 출구 주소를 사용한다면 설정에 모두 반영하세요. 그렇지 않으면 올바른 키도 검증을 통과하지 못할 수 있습니다. IP 제한은 프로젝트와 섹션 선택을 보완하며, 이를 대신하지 않습니다.

필요하면 «만료»를 설정하세요. 선택한 날짜의 UTC 기준 하루가 끝날 때까지 유효합니다. 연동 운영 기간과 맞추어 설정하세요. 키가 만료되었다는 사실은 고객이 결제하지 않았다는 증거가 아닙니다.

5. 키를 만들고 비밀 값 보관하기

«키 만들기»를 누르고, 계정 화면에서 보안 확인을 요청하면 완료하세요. 표시된 창에서 비밀 값을 복사해 주문 확인 프로세스의 서버에 보관합니다. 클라이언트 JavaScript, 결제 링크, 구매자와의 대화, 공개 로그에 넣지 마세요.

창을 닫은 후 목록에서 비밀 값을 복구할 수 있다고 기대하지 마세요. 목록에는 키를 축약한 표기만 표시됩니다. 접근 범위를 표시하는 «언어: 영어» 항목, 프로젝트, 허용된 섹션, 만료일, 상태를 확인하세요. 개발자에게 접근 권한을 제공해야 한다면 적절한 보안 저장소를 사용하고, 안내문과 함께 키를 공개하지 마세요.

6. 허용되는 접근과 차단되는 접근 확인하기

허용된 IP를 사용하는 서버에서 해당 프로젝트의 이미 알고 있는 인보이스를 읽으세요. 아래는 API 카탈로그의 조회 예제입니다. 자신의 인보이스 ID와 생성한 키를 사용하세요.

#!/usr/bin/env bash
set -euo pipefail
: "${CRYPTANIO_RESOURCE_ID:?Set CRYPTANIO_RESOURCE_ID}"
: "${CRYPTANIO_API_KEY:?Set CRYPTANIO_API_KEY}"
urlencode() {
  local LC_ALL=C text="$1" char index
  for ((index=0; index<${#text}; index++)); do
    char="${text:index:1}"
    case "$char" in [a-zA-Z0-9.~_-]) printf '%s' "$char" ;; *) printf '%%%02X' "'$char" ;; esac
  done
}
response_file="$(mktemp)"
trap 'rm -f "$response_file"' EXIT
transfer_status=0
http_status="$(curl \
  --silent --show-error --max-time 30 --request GET \
  --header "Authorization: Bearer $CRYPTANIO_API_KEY" \
  --header 'Accept: application/json' \
  "https://api.cryptanio.com/v1/invoices/$(urlencode "$CRYPTANIO_RESOURCE_ID")" \
  --output "$response_file" --write-out '%{http_code}')" || transfer_status=$?
if [[ "$http_status" == 2?? ]]; then
  cat "$response_file"
  exit "$transfer_status"
fi
printf 'HTTP %s\n' "$http_status" >&2
cat "$response_file" >&2
exit 1

예제 다운로드

그다음 본인 소유의 다른 프로젝트에 있는 알려진 인보이스로 접근 제한을 확인하세요. 그 인보이스의 데이터는 반환되면 안 됩니다. 목록도 선택한 프로젝트 안으로 제한되어야 합니다. 이 키는 «인보이스» 섹션이 활성화되어 있어도 인보이스를 생성하거나 수정할 수 없습니다. 이후의 결제 확인 절차는 API로 결제를 확인하는 방법에서 설명합니다.

요청이 실패하면 프로젝트, 모드, IP, 만료일, 권한을 확인하세요. 접근 오류 한 건만으로 미결제라고 판단하거나 제한된 키 대신 계정 전체에 접근하는 키를 넣지 마세요. 결제 여부는 인보이스의 상태로 판단합니다.

나중에 접근 권한 조정하기

기존 키에서 «오시는 길»을 누르고 프로젝트, 섹션, IP, 만료일을 변경한 뒤 «접근 권한 저장»을 선택하세요. 모드는 키 생성 시 선택합니다. «회전»은 비밀 값을 바꾸고 이전 값을 즉시 비활성화하며, «관련 기사»는 키를 폐기해 사용을 중단합니다. 키를 교체하기 전에 서버 클라이언트의 업데이트를 준비하여 주문 확인이 중단되지 않도록 하세요.

관련 글