API 키 — tnea_ & tnsr_¶

NumerologyAPI는 두 종류의 API 키를 사용합니다. 두 키 모두 형태가 비슷하고, 동일한 80자 보안 형식으로 생성되며, 동일한 X-API-Key 헤더로 인증됩니다 — 하지만 측정(과금) 방식이 다르며 서로 다른 제품을 위해 만들어졌습니다.

1. 키 형식 및 보안¶

모든 키는 정확히 80자 길이입니다:

tnea_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
tnsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• 4자리 접두사가 키 유형을 식별하며, 나머지 75자는 암호학적으로 안전한 난수 소스를 사용해 생성됩니다.
• 키는 서버 측에 SHA-256 해시로 저장됩니다. 평문 키는 생성 시점에 단 한 번만 표시됩니다.
• 키가 유출된 적이 있다면, 대시보드에서 즉시 순환(rotate) 하세요.

2. 플랫폼 키 (tnea_)¶

플랫폼 키는 NumerologyAPI를 자체 제품 — 웹사이트, 모바일 앱, 서버 측 서비스 — 에 통합하기 위한 표준 키입니다.

인증¶

모든 요청에 X-API-Key 헤더를 사용해 키를 보내세요:

curl --request GET \
  --url "https://api.numerologyapi.com/api/v1/life_path?birth_year=1990&birth_month=5&birth_day=15" \
  --header "x-api-key: tnea_YOUR_API_KEY"

과금 방식¶

과금 대상 /api/v1 호출은 조직의 크레딧 지갑(선불제)에서 차감됩니다. 지갑은 대시보드에서 언제든지 충전할 수 있습니다.

채널 규칙: 플랫폼 키는 X-Numora-Client 헤더를 보내면 안 됩니다. 이 헤더를 보내면 403이 반환됩니다 — 해당 헤더는 데스크톱 채널 전용입니다.

3. Numora Studio 키 (tnsr_)¶

Numora Studio 키는 실무자(practitioner)가 고객 리포트를 생성하는 데 사용하는 Numora Studio 데스크톱 앱(macOS/Windows)을 인증합니다. 이 키는 플랫폼 키와 동일한 형식을 가지는 형제 키이지만, 플랫폼 크레딧 대신 조직의 Numora Studio 요금제 허용량에 대해 과금됩니다.

프로비저닝¶

tnsr_ 키는 다음 두 가지 방법 중 하나로 생성됩니다:

• 데스크톱 앱 로그인 흐름을 통해서(브라우저 동의 페이지가 키를 자동으로 프로비저닝), 또는
• 대시보드의 API 키 페이지(/api-keys)에서 수동으로.

채널 서명(필수)¶

tnsr_ 키로 이루어지는 모든 호출에는 데스크톱 채널 헤더가 포함되어야 합니다:

서버 측 강제 규칙:

• X-Numora-Client가 없는 tnsr_ 키 → 403.
• X-Numora-Client가 있는 tnea_ 키 → 403.

과금 방식¶

• 과금 대상 /api/v1 호출은 조직의 Numora Studio 요금제 허용량에서 차감됩니다(조직의 모든 tnsr_ 키가 공유하는 단일 풀).
• tnsr_ 키별 크레딧 폴백(credit fallback) 토글이 있습니다: 요금제 허용량이 소진되면 키가 조직의 플랫폼 크레딧으로 폴백될 수 있습니다 (기본값: 꺼짐).
• 허용량이 소진되고 폴백이 활성화되지 않은 경우 호출은 429를 반환합니다.

기기 잠금(선택 사항)¶

tnsr_ 키는 등록된 기기에 잠글 수 있습니다. 잠금이 활성화되면 모든 요청에 조직에 등록된 X-Numora-Device-Id가 포함되어야 하며, 등록되지 않은 기기는 403으로 거부됩니다.

데스크톱 전용 엔드포인트¶

일부 엔드포인트는 데스크톱 채널 전용으로 예약되어 있으며, tnea_ 키에는 403을 반환합니다:

• POST /api/v1/numora/report-bundle — 전체 고객 리포트를 한 번의 호출로
• POST /api/v1/numora/order — 앱 내 요금제/허용량 구매 흐름
• POST /api/v1/numora/devices/register — 데스크톱 설치 등록
• GET /api/v1/numora/studio-status — 데스크톱 잔액 및 할당량 미터

팁: 과금 대상 응답에는 X-Remaining-Credits 및 X-Remaining-Tokens 헤더도 포함되므로, 추가 호출 없이 실시간 잔액을 추적할 수 있습니다.

4. 키 관리(대시보드)¶

대시보드의 API 키 페이지(/api-keys)는 두 키 유형 모두의 제어 센터입니다.

역할: admin과 developer 역할은 키를 생성하고 관리할 수 있습니다. finance는 프로덕션 API 키를 생성할 수 없습니다. 재무 작업(요금제 구매, 충전)은 admin과 finance로 제한됩니다.

여러 키: 조직은 두 유형의 키를 여러 개 보유할 수 있습니다 — 예를 들어 실무자별 또는 데스크톱 설치별로 tnsr_ 키 하나씩. 허용량은 조직별로 공유되므로 키가 자체 잔액을 두고 "경쟁"하지 않습니다.

5. 모범 사례¶

• 키를 비밀번호처럼 취급하세요. 클라이언트 측 코드, 공개 저장소 또는 로그에 절대 포함하지 마세요.
• 백엔드에서 환경 변수 또는 시크릿 관리자를 사용하세요.
• 키가 유출되거나 팀원이 퇴사하면 즉시 순환하세요.
• 기기 관리와 폐기를 간소화하려면 데스크톱 설치별로 tnsr_ 키 하나를 사용하세요.
• 보안 수준이 높은 조직은 기기 잠금을 활성화하세요.
• 예상치 못한 사용량 급증을 조기에 발견하려면 대시보드에서 사용량을 모니터링하세요.

6. 자주 묻는 질문¶

tnsr_ 키로 일반 플랫폼 엔드포인트를 호출할 수 있나요? 네. Numora Studio 키는 전체 /api/v1 표면을 인증하며, 해당 호출은 Numora Studio 요금제 허용량에 대해 과금됩니다.

tnea_ 키로 데스크톱 전용 /numora/* 엔드포인트를 호출할 수 있나요? 아니요. 데스크톱 전용 엔드포인트는 플랫폼 키에 대해 403을 반환합니다.

tnsr_ 키로 호출할 때 왜 403이 발생하나요? 대부분 X-Numora-Client 헤더가 누락되었거나 앱 ID가 일치하지 않기 때문입니다. 모든 요청에 X-Numora-Client: numora-studio/<version>이 포함되어 있는지 확인하세요.

tnea_ 키로 호출할 때 왜 403이 발생하나요? 플랫폼 키는 X-Numora-Client 헤더를 포함해서는 안 됩니다 — 제거하세요.

허용량이 소진되면 어떻게 되나요? tnsr_ 키에 크레딧 폴백이 활성화되어 있지 않거나(tnea_ 키의 경우 플랫폼 지갑을 충전하지 않았다면) 과금 대상 호출은 429를 반환합니다.

관련 문서¶

• 시작하기
• 요금제
• 기업 솔루션