認証

API は、組織の API キーでサーバーを認証します。キーは（個人ではなく）組織に属し、一連の権限を持ち、 テストまたは本番のどちらか一方のモードでのみ動作します。

キーの送信

次のどちらかのヘッダーを使用します。

# Authorization header (recommended)
curl https://api.bonafidesign.com/v1/envelopes -H "Authorization: Bearer bf_live_…"

# or x-api-key
curl https://api.bonafidesign.com/v1/envelopes -H "x-api-key: bf_live_…"

キーは bf_live_… または bf_test_… の形式です。キーがない場合は 401（unauthorized）になります。形式が不正なキー、失効したキー、期限切れのキーも 401 です。キーはサーバー上に保管し、ブラウザやモバイルアプリには絶対に含めないでください。ブラウザで署名する場合は、代わりに署名セッションを発行します。

テストキーと本番キー

	テスト（`bf_test_…`）	本番（`bf_live_…`）
ドキュメント	`TEST` の透かし入りでレンダリング	透かしなし
メール	組織のメンバーにのみ配信	すべての受信者に配信
課金	無料・無制限で、計上されない	完了したエンベロープがプランの利用量に計上される
データ	キーで作成したエンベロープ、リンク、Webhook エンドポイントはテストモード	本番モード

モードはキーによって決まり、リクエストによって決まることはありません。POST /v1/envelopes の ?test_mode=true はダッシュボードセッションにのみ適用されます。一覧（GET /v1/envelopes、GET /v1/signing-links）はキーと同じモードのものだけを返し、エンベロープのイベントは同じモードの Webhook エンドポイントにのみ送信されます。すべてのエンベロープと Webhook ペイロードには、どちらのモードかが示されます（testMode）。

キーの作成と失効

キーはダッシュボードの設定 › API キーで、 apikey:manage 権限を持つメンバー（オーナーと管理者）が管理します。シークレットが表示されるのは、キーの作成時の一度だけです。キーには名前、モード、有効期限（1〜365 日、または無期限）、スコープを設定できます。

スコープ

キーのスコープとは、そのキーが使用できる組織の権限です。デフォルトでは、新しいキーには作成者の権限から管理系の権限（org:manage、member:manage、 sso:manage、apikey:manage、billing:manage）を除いたものが付与されます。また、自分が持っていない権限をキーに付与することは誰にもできません。キーのスコープ外の呼び出しは 403 となり、不足している権限が示されます。

{
  "type": "https://bonafidesign.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Missing permission: envelope:send.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

権限	キーで可能になる操作
`template:read`	テンプレート、バージョン、およびその PDF の一覧取得と読み取り
`template:write`	テンプレートの作成、ファイルのアップロード、下書きの保存、未使用テンプレートの削除
`template:publish`	下書きを新しいバージョンとして公開
`envelope:read`	エンベロープ、ドキュメント、監査証跡の一覧取得と読み取り、署名リンクの一覧取得
`envelope:send`	エンベロープ、署名セッション、署名リンクの作成、リンクの再送
`envelope:void`	進行中のエンベロープの無効化
`org:manage`	Webhook エンドポイントの管理とイベントの再配信、組織設定の読み取り
`billing:manage`	利用量（`GET /v1/usage`）と請求金額の読み取り

Webhook エンドポイントの管理には org:manage が必要ですが、この権限はデフォルトではキーに付与されません。エンドポイントはダッシュボードで登録するか、このスコープを明示的に指定したキーを作成してください。

エンドポイントごとの認証方式

API リファレンスの各オペレーションには、そのセキュリティスキームが記載されています。概要は次のとおりです。

API キーまたはダッシュボードセッション：テンプレート、エンベロープ、署名セッション、署名リンク、Webhook エンドポイント、組織設定、請求の概要と利用量。
ダッシュボードセッションのみ：API キー、SCIM トークン、SSO 接続設定、組織ロゴのアップロード、請求の決済とポータル、 Webhook シークレットの表示。
署名者トークン：/v1/signing/*。ホスト型ページと <bf-signing> が、セッショントークン（bfs_…）またはそれと交換したアクセストークン（bfa_…）を使って利用します。
公開：/v1/links/{id}（常設リンク）、/v1/sso/discover、および検証 API （/v1/public/*、/.well-known/bona-fide/keys.json）。

ダッシュボードへのログイン

（サーバーではなく）人は、https://app.bonafidesign.com/sign-in からダッシュボードにログインします。デフォルトはメールアドレスとパスワードです。そのほか、メールで届く 6 桁のコード（代わりにコードをメールで受け取る）、マジックリンク、パスキー、Google または Microsoft、会社の SSO も利用できます。

パスワードでアカウントを作成すると、メールが 1 通送信されます。そのアドレスがあなたのものであることを確認するためのコードです。確認が済むまで、そのパスワードではログインできません。すでにアカウントがあるアドレスで登録しても何も変更されず、新規登録の場合とまったく同じ応答が返されます。そのアドレスの所有者には、代わりにログイン方法を説明するメールが届きます。
パスワードは 12〜128 文字で、ソルト付きの scrypt ハッシュとして保存されます。既知のデータ侵害に含まれている新しいパスワードは拒否されます。 Have I Been Pwned に送信されるのは SHA-1 ハッシュの先頭 5 文字だけで（k-匿名性）、パスワード自体が送信されることはありません。このサービスが 2 秒以内に応答しない場合、パスワードはチェックなしで受け入れられます。
パスワードを忘れた場合は、リセット用のメールのリンクから新しいパスワードを設定するページに移動します。リンクは 1 回だけ使え、 1 時間で期限切れになります。リンクを使用すると、すべてのデバイスでログアウトされます。
まだパスワードがない場合：コード、リンク、パスキー、Google / Microsoft で作成したアカウントは引き続きその方法でログインでき、設定 › アカウントでパスワードを追加できます。最初のパスワードを設定するには、過去 15 分以内にログインしている必要があります（本人確認のため、ページからコードがメールで送信されます）。パスワードを変更するには現在のパスワードが必要です。どちらの場合も、ほかのセッションはログアウトされます。
エラーからアカウントの存在がわかることはありません。パスワードの誤り、未登録のアドレス、パスワードのないアカウントには同じ応答が返され、リセットのリクエストには常に、メールを送信したと応答します。
レート制限：パスワードによるログイン、新規登録、リセットのリクエストは、IP アドレスごと、およびメールアドレスごとに制限されます。上限を超えると、期間が過ぎるまで 429 が返されます。
会社の SSO：組織が SSO を強制している場合、その組織のメールドメインのメンバーは ID プロバイダー経由でのみログインできます。パスワード、コード、マジックリンクは拒否されます。オーナーは緊急時のログイン手段として、メールのコードを引き続き使用できます。

リクエスト ID

すべてのレスポンスには x-request-id ヘッダーが、すべてのエラー本文には requestId が含まれます。ログを関連付けるために、独自の x-request-id（A-Z a-z 0-9 . _ - で構成される 8〜128 文字）を送信することもできます。送信しない場合は API が生成します。サポートに問い合わせる際は、この ID をお伝えください。