KYC の Key と認証方式

サーバー API Key はアプリケーションまたはプロジェクトを識別するための値です。サーバー間の公開 API 呼び出しだけに使用し、ブラウザーコード、モバイルアプリ、URL、Hosted ページには置かないでください。

Hosted JWT は、Finger KYC が Hosted KYC または KYB セッション向けに発行する、profile に紐づいた短期資格情報です。有効期限は30分です。

FingerGrid SSO Access Token は FingerGrid ユーザーを認証するためのもので、KYC API Key とは別物です。FingerGrid/OIDC フローが必要な場合だけ使用します。

profileId は1件の KYC または KYB リソースを識別する ID です。資格情報ではなく、単独でアクセス権を与えるものでもありません。

• API Key：サーバーアプリケーションの資格情報
• Hosted JWT：一時的なブラウザフロー用資格情報
• SSO Access Token：FingerGrid ユーザー認証
• profileId：リソース ID であり秘密情報ではない

バックエンドから https://api.fingerkyc.com/public/v1 を呼び出すときは Authorization: Bearer <API_KEY> を使用します。API Key は profile の作成・読み取り、Hosted JWT の作成、プロジェクトに許可されたデータの読み取りに使います。

Hosted JWT は Hosted KYC または KYB のブラウザフローだけで使用します。リダイレクト直前にサーバーで発行し、対象 profileId に紐づけてください。期限切れ後は新しく発行します。

公開 API は匿名 API ではありません。Finger KYC Gateway とドキュメントの /public/v1 パスを使ってください。内部 /api/v1 パスは顧客向け契約ではありません。

• バックエンド API：Authorization: Bearer <API_KEY>
• Hosted フロー：サーバーが JWT を発行し、ブラウザーは Hosted JWT だけを受け取る
• profileId はパス、認証情報は Header に入れる
• /public/v1 を使用し、内部 /api/v1 は呼び出さない

バックエンドでサーバー API Key を使って KYC または KYB profile を作成し、返された profileId を自社データベースに保存します。その後、対象 profile 用の Hosted JWT を作成してユーザーをリダイレクトします。API Key をブラウザーへ渡してはいけません。

ユーザーが手順を完了したら、バックエンドから profile の状態またはスナップショットを読み取ります。Hosted JWT は対象 profile の Hosted 操作に限定され、アプリケーション側の読み取り用 API Key の代わりにはなりません。

• サーバーで profile を作成する
• 自社データベースに profileId を保存する
• 有効期限30分の Hosted JWT を発行する
• API Key を公開せず Hosted フローを開く
• 最終状態はバックエンドから読み取る

API Key はサーバー側のシークレット管理または保護されたサーバー設定にだけ保存してください。担当者、プロジェクト、環境が変わったらローテーションし、Git やフロントエンド JavaScript に含めないでください。

Hosted JWT の有効期限は30分です。Hosted ページで期限切れが表示されたら、ユーザーをアプリケーションへ戻し、サーバーから同じ profileId 用の新しい Hosted JWT を発行します。ユーザーに Key を手入力させないでください。

内部 provisioning key は Finger KYC のコンポーネントが Hosted JWT を発行または検証するためだけに使います。顧客 API 資格情報ではないため、ブラウザーや外部連携から送信してはいけません。

• API Key や provisioning key をブラウザーに公開しない
• profileId を Bearer 資格情報として使わない
• Hosted JWT は短期かつ profile 単位の資格情報として扱う
• 期限切れ後は Hosted JWT を再発行する
• 障害調査では Request ID と安全なエラーコードを使う