AceDataCloud의 프로덕션 API 거버넌스

프로덕션 API 키는 단순한 비밀 문자열이 아닙니다. 이는 누가 무엇을 호출할 수 있는지, 얼마나 소비할 수 있는지, 액세스가 얼마나 오래 지속되는지, 어떤 애플리케이션이 비용을 지불하는지, 그리고 인시던트를 어떻게 추적할 수 있는지를 위한 제어 지점입니다.

AceDataCloud는 연결된 네 개의 계층에 걸쳐 이러한 제어 기능을 제공합니다.

1. 자격 증명 발급 — 특정 애플리케이션을 위한 키를 생성합니다.
2. 애플리케이션 잔액 정책 — 사용량이 어디에서 차감되는지와 할당량이 부족할 때 발생하는 일을 결정합니다.
3. 사용량 관측 가능성 — 상태, 비용, 지연 시간, API, 애플리케이션 및 자격 증명을 추적합니다.
4. 자격 증명 수명 주기 — 제한을 업데이트하고, 시크릿을 교체하며, 액세스를 취소합니다.

이 가이드는 플랫폼의 개별 관리 API를 하나의 실용적인 운영 모델로 전환합니다.

¶ 먼저 두 종류의 자격 증명을 구분하세요

AceDataCloud는 서로 다른 표면에 대해 서로 다른 자격 증명을 사용합니다.

자격 증명	사용처	일반적인 호스트
계정 토큰 / 플랫폼 토큰	계정 관리: 애플리케이션, 자격 증명, 잔액, 사용량, 주문	platform.acedata.cloud/api/v1/**
API 자격 증명	서비스의 비즈니스 API 호출	api.acedata.cloud/**

이들은 서로 교환하여 사용할 수 없습니다. 비즈니스 API 자격 증명을 관리 엔드포인트 호출에 사용해서는 안 되며, 플랫폼 토큰을 애플리케이션에 비즈니스 API 키로 내장해서는 안 됩니다.

이러한 분리는 유용한 보안 경계를 만듭니다.

• 플랫폼 토큰은 엄격하게 제어되는 운영 환경에 보관하세요.
• 각 워크로드에 자체 API 자격 증명을 제공하세요.
• 런타임 서비스가 필요한 비즈니스 API만 호출하도록 하세요.
• CI 또는 관리 서비스가 자격 증명 및 잔액 관리를 수행하도록 하세요.

¶ 워크로드 및 환경별로 하나의 자격 증명을 발급하세요

계정 토큰을 사용하여 POST https://platform.acedata.cloud/api/v1/credentials/로 자격 증명을 생성합니다.

최소한의 프로덕션 지향 요청에는 표시 이름, 독립적인 소비 한도, 만료 및 API 허용 목록을 포함할 수 있습니다.

curl -X POST 'https://platform.acedata.cloud/api/v1/credentials/' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d "{
    \"application_id\": \"${APPLICATION_ID}\",
    \"name\": \"prod-support-agent\",
    \"limited_amount\": 100,
    \"expired_at\": \"2027-01-01T00:00:00Z\",
    \"allowed_api_ids\": [\"${CHAT_API_ID}\"],
    \"metadata\": {\"environment\": \"production\", \"owner\": \"support-platform\"}
  }"

생성 계약은 다음을 지원합니다.

필드	거버넌스 목적
application_id	사용량을 대상 애플리케이션에 연결합니다
name	감사에서 워크로드를 식별할 수 있게 합니다
limited_amount	독립적인 자격 증명 사용 한도를 설정합니다. null은 독립적인 한도가 없음을 의미합니다
expired_at	자동으로 시간 제한된 액세스를 설정합니다
allowed_api_ids	자격 증명을 선택된 API로 제한합니다
host	해당하는 경우 자격 증명 호스트 정보를 저장합니다
for_user_id	애플리케이션 소유자가 다른 사용자를 위한 위임 자격 증명을 발급할 수 있게 합니다
tags / metadata	환경, 팀, 시스템 또는 변경 티켓 컨텍스트를 기록합니다

비어 있는 allowed_api_ids 배열은 제한 없음으로 정규화됩니다. 의도가 “아무것도 허용하지 않음”인 경우 빈 배열을 보내지 마세요. 실제 API 허용 목록을 사용하세요.

API/에이전트 서비스는 일반적으로 토큰 자격 증명을 반환합니다. 프록시 서비스는 일반적으로 사용자 이름/비밀번호 ID를 반환하며, 프록시 애플리케이션은 하나의 자격 증명만 허용합니다.

생성 응답을 민감한 정보로 취급하세요. 시크릿을 즉시 비밀번호 관리자 또는 시크릿 관리자에 저장하고 응답을 로그에 기록하지 마세요. 클라이언트는 일반 텍스트 시크릿을 나중에도 계속 검색할 수 있다고 의존해서는 안 됩니다. 수명 주기 API는 마스킹된 값을 반환할 수 있습니다.

¶ 한도를 예산만이 아니라 피해 범위 제어 수단으로 사용하세요

자격 증명 수준의 limited_amount는 유출된 키 또는 제어되지 않는 워크로드를 제한하는 데 유용하지만, 이는 비용 거버넌스의 한 부분일 뿐입니다.

견고한 계층 구조는 다음과 같습니다.

• 자격 증명 한도: 하나의 워크로드에 대한 최대 노출 범위입니다.
• 애플리케이션 잔액: 구독한 서비스 애플리케이션에 사용할 수 있는 할당량입니다.
• 전역 잔액 정책: 자격이 있는 종량제 애플리케이션을 위한 선택적 대체 수단입니다.
• 초과 인출 승인: 고객이 직접 활성화할 수 없는 별도의 읽기 전용 플랫폼 승인입니다.

이들을 동등한 것으로 취급하지 마세요.

예를 들어, 애플리케이션에 사용 가능한 할당량이 있더라도 개별 자격 증명 한도가 여전히 워크로드를 차단할 수 있습니다. 반대로 전역 잔액 공유를 활성화하면 자격이 있는 애플리케이션이 자체 잔액이 부족한 후에도 계속 사용할 수 있지만, 자격 증명 한도, 비활성화 또는 만료 검사를 제거하지는 않습니다.

¶ 단위와 상태를 포함하여 잔액을 모니터링하세요

다음으로 애플리케이션을 조회합니다.

curl --fail-with-body \
  "https://platform.acedata.cloud/api/v1/applications/${APPLICATION_ID}" \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

운영상 중요한 필드는 다음과 같습니다.

• remaining_amount — 현재 애플리케이션 할당량입니다. 음수 값은 정산 대기 중인 할당량을 나타냅니다.
• used_amount — 애플리케이션에 대해 보고된 누적 사용량입니다.
• service.unit — Credit, Count 또는 Token과 같은 단위입니다.
• disabled — 애플리케이션이 비활성화되었는지 여부입니다.
• expired_at — 구독 액세스가 만료되었는지 여부입니다.
• allow_overdraft — 관리자가 승인한 초과 인출의 읽기 전용 표시입니다.

금액이 미국 달러라고 절대 가정하지 마세요. 경고 임계값은 서비스의 실제 단위로 정의되어야 합니다.

양수 잔액만으로는 가용성이 보장되지 않습니다. 상태 확인은 잔액, disabled, 만료, 자격 증명 한도 및 서비스 상태를 평가해야 합니다. 프록시 서비스의 경우 잔액 동기화가 일시 중단되거나 시간 초과될 수 있으며, 이 경우 가장 최근에 저장된 잔액이 반환될 수 있습니다.

간결한 Python 검사:

import os
import requests

minimum = float(os.getenv("MINIMUM_BALANCE", "10"))
url = f"https://platform.acedata.cloud/api/v1/applications/{os.environ['APPLICATION_ID']}"
headers = {"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"}

response = requests.get(url, headers=headers, timeout=10)
response.raise_for_status()
application = response.json()

remaining = application.get("remaining_amount")
unit = application.get("service", {}).get("unit", "unknown")

if application.get("disabled"):
    raise RuntimeError("Application is disabled")
if application.get("expired_at"):
    print("Check whether the Application expiry has passed:", application["expired_at"])
if remaining is None:
    raise RuntimeError("No balance is available for this Application")
if not application.get("allow_overdraft", False) and float(remaining) < minimum:
    raise RuntimeError(f"Low balance: {remaining} {unit}")

여러 서비스의 경우, 모든 애플리케이션 세부 정보 엔드포인트를 높은 빈도로 폴링하는 대신 애플리케이션 목록을 한 번 가져와 각 항목을 로컬에서 평가하세요.

¶ 전역 잔액 공유 허용 여부를 명시적으로 결정하세요

자격이 있는 종량제 애플리케이션은 자체 잔액이 부족할 때 계정의 전역 잔액을 사용하도록 구성할 수 있습니다.

curl -X POST \
  "https://platform.acedata.cloud/api/v1/applications/${APPLICATION_ID}/update-allow-consume-global/" \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"allow_consume_global": true}'

반환된 allow_consume_global 값을 신뢰할 수 있는 출처로 사용하세요. 요청한 값이 저장되었다고 가정하지 마세요.

중요한 제약 사항:

• Period 애플리케이션은 전역 잔액을 소비할 수 없으며, 서버는 필드를 false로 유지합니다.
• 소유한 application_id와 계정 토큰이 필요합니다.
• allow_overdraft=true인 경우 종량제 애플리케이션은 자체 잔액이 0 아래로 내려가도 계속 차감할 수 있으며, 자체 잔액이 부족하다는 이유만으로 전역 잔액으로 전환하지 않습니다.
• 대체가 발생하면 초과 인출 동작은 실제로 비용을 지불하는 전역 애플리케이션에 의해 결정됩니다.

전역 대체는 연속성을 개선하지만 재정적 피해 범위도 넓힙니다. 기본 편의 기능이 아니라 의도적인 서비스 수준 정책으로 활성화하세요.

¶ 자격 증명별로 모든 프로덕션 호출을 추적하세요

AceDataCloud는 가장 최근 60일 동안의 API 호출 기록과 청구 요약을 보존합니다. 요청 및 응답 본문은 30일 동안 보존되며, 30~60일차의 기록은 요약을 유지하지만 더 이상 전체 metadata.request 및 metadata.response 본문을 반환하지 않습니다.

다음에서 최신 기록을 조회하세요.

curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/' \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode "credential_id=${CREDENTIAL_ID}" \
  --data-urlencode 'perspective=both' \
  --data-urlencode 'limit=100' \
  --data-urlencode 'ordering=-created_at' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

유용한 필터에는 application_id, api_id, credential_id, status_code 및 ISO 8601 시간 범위가 포함됩니다. perspective 매개변수는 세 가지 보기를 구분합니다.

• billing — 현재 계정이 비용을 지불한 호출입니다.
• actor — 현재 계정이 실제로 시작한 호출입니다.
• both — 비용을 지불한 호출과 시작한 호출의 기본 합집합입니다. 인시던트 대응을 위한 주요 필드는 다음과 같습니다:

필드	운영 용도
credential_id	노출되었거나 오작동하는 워크로드 식별
trace_id	하나의 요청을 처음부터 끝까지 조사
status_code	성공한 호출과 실패한 호출 구분
elapsed	지연 시간 추적
used_amount	원래 규칙에 따라 계산된 사용량
original_amount	Application 할인 전 사용량
deducted_amount	실제로 차감된 최종 금액
remaining_amount	청구 후 Application 할당량
actor_user_id / user_id	호출자와 결제를 담당하는 계정 구분

대규모 쿼리의 경우 더 짧은 기간(가급적 하루 이하)을 사용하고 필터를 추가하세요. 동일한 쿼리가 이미 실행 중인 경우 API는 429 usage_query_in_progress를 반환할 수 있습니다. 백오프와 함께 Retry-After를 따르세요. 503 usage_query_timeout은 즉시 반복하기보다 요청 범위를 좁혀야 한다는 신호입니다.

¶ 필요해지기 전에 로테이션 및 인시던트 워크플로를 구축하세요

실용적인 대응 플레이북은 다음과 같습니다:

1. 식별 사용량 레코드 또는 서비스 구성에서 자격 증명을 식별합니다.
2. 격리 제한을 낮추거나, 만료일을 변경하거나, allowed_api_ids를 제한하거나, 폐기하여 노출을 격리합니다.
3. 로테이션 시크릿을 교체하고 시크릿 관리자를 업데이트합니다.
4. 배포 로깅하지 않고 워크로드에 새 값을 배포합니다.
5. 검증 예상된 자격 증명 ID로 성공적인 호출을 검증합니다.
6. 검토 자격 증명, 상태, API 및 추적 ID별로 최근 레코드를 검토합니다.
7. 폐기 전환이 확인된 후 더 이상 사용되지 않는 자격 증명을 폐기합니다.

개발, 스테이징, 프로덕션, 예약 작업 및 타사 통합을 위해 별도의 자격 증명을 만드세요. 이렇게 하면 로테이션이 국지적으로 이루어지고 귀속 관계가 명확해집니다. 단일 공유 “프로덕션” 키는 장애 위험과 조사 모호성을 모두 극대화합니다.

¶ 권장 제어 기준선

각 프로덕션 워크로드에 대해:

• 전용 API 자격 증명, 환경 간 공유 금지.
• 설명적인 이름 및 소유권 메타데이터.
• 필요한 엔드포인트 ID만 포함하는 API 허용 목록.
• 예상 워크로드에 비례하는 독립적인 사용 제한.
• 계획된 갱신 기간이 있는 만료일.
• 시크릿 관리자에 저장되고 로그에서 제외된 시크릿.
• 올바른 서비스 단위의 Application 잔액 알림.
• 잔액만이 아닌 비활성화 및 만료 확인.
• allow_consume_global에 대한 명시적 결정.
• Application 및 자격 증명으로 필터링된 사용량 대시보드.
• 애플리케이션 로그에 캡처된 추적 ID.
• 문서화된 교체 및 폐기 절차.

¶ 거버넌스는 순환 구조입니다

자격 증명 발급, 잔액 모니터링 및 사용량 추적은 별도의 업무로 관리되어서는 안 됩니다. 이들은 함께 지속적인 제어 순환 구조를 형성합니다:

좁게 발급 → 비용을 지불하는 Application 모니터링 → 실제 호출 추적 → 신속하게 교체 또는 폐기.

AceDataCloud의 관리 API는 관리 액세스, 런타임 액세스, 할당량 및 청구 귀속을 혼동하지 않고 이 순환 구조를 구현하는 데 필요한 필드를 제공합니다. 결과는 단순히 더 안전한 API 키가 아닙니다. 이는 노출이 제한되고 사용량을 설명할 수 있는 프로덕션 시스템입니다.

¶ 공식 리소스

• AceDataCloud Platform API 자격 증명 생성
• AceDataCloud Application 잔액 조회
• Application 전역 잔액 공유 구성
• AceDataCloud Platform API 호출 기록 조회
• AceDataCloud Platform 콘솔