OAuth 2.1 でマルチテナント連携を構築する
ユーザーが自分の Crisphive ビジネスをあなたのプロダクトに接続できるようにします — 同意画面付きの OAuth 2.1 で、API キーをコピーすることは一切ありません。
API キーが認証するのは自分自身のビジネスです。他の Crisphive ビジネスが接続するプロダクト — CRM 同期、予約ウィジェット、AI エージェントコネクタなど — を作る場合は、代わりに組み込みの OAuth 2.1 認可サーバーを使ってください。各ビジネスオーナーが同意画面であなたのアプリを承認し、アプリはそのオーナーのテナントに紐付いたトークンを受け取ります。
/v1 API と /mcp エンドポイントです。API キーとまったく同じように Authorization: Bearer <access_token> を送信してください。フロー
サーバーは現行の OAuth 2.1 ドラフトを実装しています。PKCE（S256）は必須、クライアントはパブリック（シークレットなし）、登録は動的で、手動のアプリ審査はありません:
| ステップ | リクエスト |
|---|---|
| 1. 認可サーバーの発見 | GET /.well-known/oauth-authorization-server（RFC 8414）→ エンドポイント URL とサポートするグラント |
| 2. 登録 | POST /oauth/register（RFC 7591 動的クライアント登録）→ client_id |
| 3. 認可 | GET /oauth/authorize?… — ビジネスオーナーが Crisphive にサインインして同意します |
| 4. 交換 | POST /oauth/token（grant_type=authorization_code、code、code_verifier）→ { access_token, refresh_token, expires_in } |
| 5. リフレッシュ | POST /oauth/token（grant_type=refresh_token）→ ローテーションされたトークンペア（古いリフレッシュトークンは一度しか使えません） |
トークン
トークンは同意したオーナーのビジネス、リージョン、環境に紐付けられており、別のテナントに到達したり、ライブ↔サンドボックスを切り替えたりすることは決してできません。アクセスを制限するには、より狭い scope（スペース区切りの権限コード、例: customers_view job_requests_view）をリクエストしてください。省略するとビジネスへのフルアクセスになります。アクセストークンの有効期間は約 1 時間です。接続を維持するには、一度しか使えないリフレッシュトークンで更新してください。
接続の有効期間
接続は 2 つの独立したクロックによって管理されます。日常的に使われている連携がスケジュールで切断されることはなく、放置された連携は自然に期限切れになります。
- アイドルウィンドウ — 30 日。トークンをリフレッシュするたびに、さらに 30 日間有効な新しいリフレッシュトークンが発行されます。接続を使い続ければ無期限に延長され、30 日間使わなければ失効します。
- 絶対上限 — 90 日。アクティビティにかかわらず、接続はビジネスオーナーが承認してから 90 日後に終了します。ビジネスは Developers → MCP connections から接続ごとに 1 日から 365 日までの任意の値を設定できます。カウントダウンは変更時ではなく、最初の承認時から計測されます。
いずれかのクロックが切れるとリフレッシュは失敗し（OAUTH_GRANT_EXPIRED）、オーナーが同意画面からアプリを再承認する必要があります。リフレッシュの失敗は常に「認可フローのやり直し」として扱い、リトライ可能なエラーとして扱わないでください。接続の有効期限の 14 日前に、ビジネスのオーナーと管理者にメールが送信されます — 再承認にはオーナーがブラウザで操作する必要があるため、警告はキーの場合よりも早く届きます。
API を呼び出す
curl "https://api.crisphive.com/v1/customers" \ -H "Authorization: Bearer <access_token>"
AI エージェントコネクタを作る場合は、MCP サーバーがまさにこのフローを使います。準拠した MCP クライアントは自動で実行するため、通常 OAuth コードを書く必要はまったくありません。