APIキー — tnea_ と tnsr_¶

NumerologyAPIでは、2つのファミリーのAPIキーを使用します。どちらも見た目は似ており、同じ80文字の安全な形式で生成され、同じX-API-Keyヘッダーで認証されます。ただし、計上方法が異なり、異なる製品向けです。

1. キーの形式とセキュリティ¶

すべてのキーは正確に80文字です:

tnea_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
tnsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• 4文字のプレフィックスがキーのタイプを識別し、残りの75文字は暗号学的に安全な乱数ソースで生成されます。
• キーはサーバー側でSHA-256ハッシュ化されて保存されます。平文のキーは作成時に一度だけ表示されます。
• キーが漏洩した場合は、ダッシュボードからすぐにローテーションしてください。

2. プラットフォームキー（tnea_）¶

プラットフォームキーは、NumerologyAPIを自社の製品（Webサイト、モバイルアプリ、サーバーサイドのサービス）に統合するための標準的なキーです。

認証¶

すべてのリクエストで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キーは、実践者がクライアントレポートを生成するために使用する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_キーで共有される1つのプール）。
• tnsr_キーごとにクレジットフォールバックトグルが存在します。プラン許容量が使い果たされた場合、キーは組織のプラットフォームクレジットにフォールバックできます（初期設定はオフ）。
• 許容量が使い果たされ、フォールバックも有効でない場合、呼び出しは429を返します。

デバイスロック（オプション）¶

tnsr_キーは、登録済みのデバイスにロックできます。ロックを有効にすると、すべてのリクエストに組織に登録されたX-Numora-Device-Idを添付する必要があり、未登録のデバイスは403で拒否されます。

デスクトップ専用エンドポイント¶

一部のエンドポイントはデスクトップチャネル専用であり、tnea_キーに対しては403を返します:

• POST /api/v1/numora/report-bundle — クライアントレポート全体を1回の呼び出しで取得
• 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に限定されます。

複数キー: 組織は両タイプのキーを複数保持できます。たとえば、実践者ごとまたはデスクトップインストールごとに1つのtnsr_キーを使用できます。許容量は組織単位で共有されるため、キーがそれぞれの残高をめぐって「競合」することはありません。

5. ベストプラクティス¶

• キーはパスワードと同様に扱ってください。 クライアントサイドのコード、公開リポジトリ、またはログに埋め込まないでください。
• バックエンドでは環境変数またはシークレットマネージャーを使用してください。
• キーが侵害されたり、チームメンバーが退社した場合はすぐにローテーションしてください。
• デスクトップインストールごとに1つの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を返します。

関連ページ¶

• はじめに
• 料金プラン
• エンタープライズソリューション