API Keyとセキュリティ
認証情報を分け、送信ドメインを制限し、安全にKeyを更新・失効します。
1. 2種類のBearer認証
セッショントークンはdomains、api-keys、webhooksの管理用、API Keyは/v1/mailとSMTPパスワード用です。アカウントのパスワードや言語Cookieではありません。GET /v1/apikey/verifyはKeyを確認しますが、ドメイン検証や残枠は保証しません。
2. 作成と保存
メール確認後、空でないnameと任意の数値domain_idでPOST /api-keysを使います。完全なkeyは201作成時のみ返ります。サーバー側の秘密管理に保存し、ログ・スクリーンショット・フロントコードには残さないでください。一覧から復元できません。
| フィールド / 設定 | 型 / 状態 | 説明 |
|---|---|---|
| name | string | 作成時、空不可 |
| domain_id | uint64 | 作成時の任意ドメインID |
| key | string | 作成時のみ完全なKey |
| id / key_prefix / status | uint64 / string | 一覧情報、prefixでは認証不可 |
| allowed_domain_id / last_used_at | uint64 / time | 省略可能、常にnullの項目ではない |
curl -X POST "${SMTPDOG_API_ORIGIN}/api-keys" \
-H "Authorization: Bearer ${SMTPDOG_SESSION_TOKEN}" \
-H "Content-Type: application/json" \
--data '{"name":"Server integration","domain_id":123}'
curl -X GET "${SMTPDOG_API_ORIGIN}/api-keys" \
-H "Authorization: Bearer ${SMTPDOG_SESSION_TOKEN}"
curl -X DELETE "${SMTPDOG_API_ORIGIN}/api-keys/${SMTPDOG_KEY_ID}" \
-H "Authorization: Bearer ${SMTPDOG_SESSION_TOKEN}"3. 送信範囲を制限
domain_id省略時はアカウントの検証済みドメイン、指定時はそのドメインのみ送信できます。作成時に所有、送信時にverifiedを確認します。有効期限、ロール、範囲の直接変更は未対応です。所有権検証や不正利用対策を省略しません。
4. 更新と失効
新Key作成、サービス設定更新、切り替え確認、DELETE /api-keys/{id}で旧Key失効の順です。204は本文なしで、新規リクエストには使えません。直接更新や明文復元APIはありません。セッショントークンを誤用した場合は認証方式を確認してください。