メインコンテンツに移動

APIキー

APIキー(個人用アクセストークン)は、サーバー側のスクリプト、サードパーティ製コネクタ(Zapier、Make、Google Sheets)、またはOAuthの完全なフローを用意するほどでもない場面で、B1 APIに認証するもっとも簡単な方法です。キーは特定の教会内の特定の人物に紐づき、その人物の権限を引き継ぎます。任意のスコープを設定すると、権限をさらに絞り込めます。

始める前に

  • キーを作成・管理できるのは、Edit Settings 権限を持つ教会の管理者です
  • 生のキーは作成時に一度だけ表示されます。すぐに安全な場所に保存してください
  • すべてのAPIリクエストはHTTPSを使用する必要があります

キーの形式​

B1 APIキーは次のような形式です:

cak_<prefix>.<secret>
  • cak_ — 固定の識別子(認証レイヤーが照合するAPIキーのプレフィックス)
  • <prefix> — 8文字の公開検索用セグメント
  • <secret> — 48文字の秘密鍵。サーバー側に保存されるのはSHA-256ハッシュのみです

キーは標準のBearerヘッダーでサーバーに提示されます:

Authorization: Bearer cak_a1b2c3d4.f0e1d2c3b4a5968778695a4b3c2d1e0f1a2b3c4d5e6f7

APIの認証レイヤーは、cak_ で始まるトークンをすべてAPIキーの処理経路に振り分けます。秘密鍵をハッシュ化し、プレフィックスで検索して、キーに紐づく人物の現在の権限を解決します。そのため、B1Adminで権限を取り消すと次のリクエストから即座に反映され、キーがロールと食い違うことはありません。

キーの作成(B1Admin)​

  1. Edit Settings 権限を持つユーザーとしてB1Adminにサインインします。
  2. Settings → Developer → API Keys を開きます。
  3. New API Key をクリックし、わかりやすい名前(例: 「Zapier — donations sync」)を付け、キーに与えるスコープを選択して Save をクリックします。
  4. 完全な cak_… キーがダイアログに一度だけ表示されます。ダイアログを閉じる前に、連携先の設定にコピーしてください。後から取得する方法はありません。必要であれば、いつでも新しいキーを作成できます。

スコープ​

スコープはキーにできることを絞り込みます。基になる人物が持っていない権限を与えることはできません。スコープが空、または未指定の場合、キーはその人物の権限をすべて持ちます。

スコープ許可される操作
people:read / people:write人物、世帯、グループメンバーの閲覧/編集
groups:read / groups:writeグループおよびそのメンバーシップの閲覧/編集
donations:read / donations:write献金の閲覧/記録
attendance:read / attendance:write出席、セッション、チェックインの閲覧/記録
forms:writeフォームの管理(読み取りアクセスは書き込みに含まれます)
content:read / content:writeウェブサイトのコンテンツ、登録、配信の閲覧/編集
messaging:read / messaging:writeメッセージの閲覧。書き込みではSMSの送信も可能になります
roles:read / roles:writeロール定義の閲覧/編集
settings:read / settings:write教会設定の閲覧/編集(プログラムからWebhookを登録するには必須です)
workflows:read / workflows:writeワークフローとタスクの閲覧/ワークフローの実行と編集。ワークフローを実行すると、メールやテキストメッセージの送信、Webhookの発火、グループメンバーシップの変更が行われる場合があります
offline_access長期間有効なリフレッシュトークンを許可します(OAuthフローのみ。APIキーには影響しません)

write スコープには、対応する read スコープが暗黙的に含まれます。サーバー管理者およびドメイン管理者の権限は、意図的にスコープとして公開されていません。スコープ付きの認証情報が、サイト管理者の権限に昇格することはありません。

ヒント

Webhookの登録(例: Zapier や Make の連携)にキーを使う場合、そのキーには settings:write が必要です。people:read のみのキーでは、POST /membership/webhooks が403エラーを返し、エラーメッセージは表示されません。

キーの使い方​

他のBearerトークンと同じです。認証が必要なすべてのエンドポイントは、JWTと同じようにAPIキーを受け付けます:

curl https://api.churchapps.org/membership/people \
-H "Authorization: Bearer cak_a1b2c3d4.f0e1d2c3b4a5968778695a4b3c2d1e0f1a2b3c4d5e6f7"

キーのスコープが不足しているリクエストには、権限拒否エラーと同じ形式の 403 Forbidden が返されます。

APIでのキー管理​

すべてのエンドポイントは、Membershipモジュールの /membership/apiKeys パスの下にあります。これらのエンドポイントには、Edit Settings 権限を持つ教会管理者のJWT(APIキーではない)が必要です。

メソッドとパス用途
GET /membership/apiKeys教会のキーを一覧表示します(秘密鍵は含まれず、id、name、prefix、scopes、lastUsedAt、expiresAt、createdAt のみ)
GET /membership/apiKeys/scopes利用可能なすべてのスコープ名の一覧。キー作成画面で使用します
POST /membership/apiKeys新しいキーを作成します。リクエストボディ: { "name": "...", "scopes": ["people:read"] }。レスポンスには生の cak_… キーが一度だけ含まれます
DELETE /membership/apiKeys/:idキーを取り消します。次のリクエストから有効でなくなります

取り消されたキーは即座に無効になり、猶予期間はありません。

ベストプラクティス​

  • 連携ごとに1つのキーを使う。 漏えいが疑われる場合でも、他の連携に影響を与えずに1つのキーだけを取り消せます。
  • 機能するなかで最も狭いスコープを選ぶ。 Google Sheetsへのエクスポートには people:read だけで十分で、settings:write は不要です。
  • キーは実在するスタッフではなく、サービスアカウントに紐づける。 スタッフが退職すると、そのスタッフのB1アクセスは終了し、そのスタッフの身元で発行されたキーもすべて無効になります。
  • キーはシークレットマネージャーに保存する。 ホスティングサービスの環境変数、AWS Secrets Managerなどを使用し、ソース管理には決して含めないでください。
  • 漏えいが疑われる場合はキーをローテーションする。 新しいキーを作成し、連携先を更新してから、古いキーを削除します。

OAuthとの違い​

APIキーは、教会がその連携を唯一利用している場合に適しています。B1コミュニティ全体で共有されるSaaSアプリのように、多数の教会にアクセスする必要があり、各教会の明示的な同意を得るコネクタの場合は、代わりに OAuthと接続済みアプリ を使用してください。

APIキーOAuth
インストールする人1人の教会管理者各教会の管理者がアプリを承認
認証ヘッダーAuthorization: Bearer cak_…Authorization: Bearer <jwt>
トークンの有効期間取り消されるまでアクセス約7日、リフレッシュ約90日
最適な用途社内スクリプト、Zapier/Make/Sheetsコネクタ複数テナントのサードパーティアプリ