登録と設定

連携の前に、デベロッパポータルで OAuth / OIDC クライアント（画面上は識別子）を作成し、リダイレクト URI と権限を設定し、クライアント種別に応じた資格情報を取得してください。プロトコル連携（認可コード、トークン、同意ページなど）は、このディレクトリの「連携の概要」以降を参照してください。

2026-08-11：識別子の権限はポータルで編集できます。必須権限には理由とプライバシーポリシーが必要です。ユーザーはサインインのたびに認可を確認します。変更内容は同ディレクトリ「更新」の「2026-08-11 権限と同意のプラットフォーム更新」を参照してください。

入口

1. アカウントで develop.swaymoon.com にサインインします。
2. ホームの「予定リソース」から識別子を開きます（サイドバーにも同名の入口があります）。
3. 左上の + をクリックし、「アプリ識別子を登録」ウィザードを開きます。
4. ウィザードを順に完了します：説明 → アイコン → リダイレクト URI → 機能 → 確認。

デベロッパポータルはアカウント API（https://api-passport.swaymoon.com/api/v1/developer/...）でクライアントを管理します。操作の前にアカウントへサインインしてください。

クライアントの種類

3 種類とも PKCE（S256）必須です。ユーザーは認可ページで明示的に確認してからサインインします（「以前に認可済み」でも黙ってスキップしません）。クライアント種類は作成後相互に変更できません。

JWT アサーションとは

private_key_jwt は OAuth 2.0 / OpenID Connect のクライアント認証方式です（RFC 7523）。トークン交換時、サーバーが保管する秘密鍵で短命な JWT（client_assertion）に署名し、アカウントはポータルに登録した公開鍵で検証します。機密クライアントであることに変わりはありません。秘密鍵はサーバーから出してはいけません。身分証明の材料が「共有の client_secret」から「非対称鍵」に変わるだけです。

JWT アサーションを選ぶ：サーバーアプリで、長期の client_secret を環境変数に置きたくない、または無停止で鍵をローテーションしたいとき。
選ばない：純ブラウザ SPA、秘密鍵を保管できない静的サイト。非機密クライアントを使ってください。

client_assertion に必要なクレームとリクエスト形式は「認可コードと PKCE」「例とトラブルシューティング」を参照してください。

ウィザードの項目

作成結果

機密クライアント

設定の要点：

• 認証方式：client_secret_basic
• 認可タイプ：authorization_code、refresh_token
• Access Token は約 5 分；Refresh Token は約 180 日（更新後は古い Refresh Token を再利用しません）

非機密クライアント

設定の要点：

• 認証方式：none
• 認可タイプ：authorization_code のみ（refresh_token は発行しません。Access Token 期限切れ後は認可コードフローをやり直します）
• Access Token は約 5 分
• トークン交換時はリクエスト本文に client_id と code_verifier を送ります。HTTP Basic は使わないでください
• 実行できる連携は「Python の最小実行例」。AI 支援は「生成 AI で機密クライアントを連携する」「生成 AI で非機密クライアントを連携する」

JWT アサーションクライアント

設定の要点：

• 認証方式：private_key_jwt（client_assertion + ES256）
• 認可タイプ：authorization_code、refresh_token
• Access Token は約 5 分；Refresh Token は約 180 日
• トークン交換時は client_id、code_verifier、client_assertion を送ります。HTTP Basic は使わないでください
• 秘密鍵はサーバー側に残します。ポータルは秘密鍵 JWK を拒否します

リダイレクト URI（Redirect URI）の規則

• 空でない URI を少なくとも 1 件指定してください。
• 認可リクエストの redirect_uri は登録値と1 文字単位で一致する必要があります（scheme、host、port、path、query を含む）。
• Redirect URI に #fragment を使わないでください（プロトコルで禁止）。
• 本番では https:// を強く推奨します。ローカル開発では http://127.0.0.1:... などのループバックを使えますが、サーバーの検証方針に従ってください。
• ワイルドカードドメインは使えません。環境ごとに対応する URI を登録してください。
• http://127.0.0.1 と http://localhost は別アドレスです。
• 誰がアクセスするか：認可完了後、ユーザーのブラウザがここに遷移します。http://127.0.0.1:8766/callback を登録すれば、ブラウザとローカル demo が同一マシンならログインコールバックが届きます。

データ削除コールバック URL

任意です。ユーザーがアカウントのプライバシーセンターで「取り消しとデータ削除のリクエスト」を選ぶと、アカウントは次を行います：

1. そのアプリへの認可を取り消す；
2. アプリ担当者の紐づけメールへ説明メールを送る；
3. この URL が設定されていれば、アカウント API プロセスが動いているマシンからその URL へ POST します（署名の取り決めは「権限と同意」）。

実行できる連携は、「Python の最小実行例」の機密クライアント節「データ削除コールバックのデモ」です。

プライバシーポリシーのリンク

任意です。登録後、ユーザーは次から閲覧・オープンできます：

• 認可の同意ページ（設定済みの場合）；
• アカウント プライバシー → アプリの認可 → アプリ詳細；

ジャンプ前に、アカウントは次を表示します：このドメインは Swaymoon の管理下にありません。その内容は Swaymoon が管理していません。

本番公開前に、誰でも開ける HTTPS のプライバシーポリシーページを用意し、認可前にデータの扱いを説明できるようにしてください。

権限の推奨

openid は常に必須です。email やプロフィール細目を必須にするときは、ユーザーに見える理由とプライバシーポリシーのリンクが必要です。任意権限は同意ページで既定チェック、ユーザーは外せます。「権限と同意」を参照してください。

管理操作

• 一覧：作成済み識別子、名称、client_id、クライアント種類と認証方式、必須 / 任意権限を確認します。
• 詳細：コールバック、プライバシーポリシー、権限、webhook シークレットの発行有無、JWT 公開鍵 kid を確認します。
• 編集：説明（名称）、アイコン、リダイレクト URI、データ削除コールバック URL、プライバシーポリシーのリンク、必須 / 任意権限と必須権限の理由を変更できます。
• シークレットのローテーション：機密クライアントは詳細ページで client_secret をローテーションできます（削除コールバックの署名鍵も更新されます）。非機密 / JWT は webhookSecret を発行またはローテーションできます。
• 公開鍵の追加：JWT アサーションクライアントは詳細ページから別の公開鍵（kid）を追加でき、無停止でローテーションできます。
• 編集不可：クライアント種類（機密 / 非機密 / JWT アサーション）は作成後固定です。種類を変えるには古い識別子を削除して再登録し、アプリ内の設定を更新してください。
• 削除：識別子を削除すると、発行済みトークンはそのクライアントで使えなくなり、ユーザー側の認可関係も無効になります。

互換の案内：すでに本番運用中の古いクライアントは、プラットフォームが「編集可能な権限 / 必須の認可確認」に対応したからといってコード変更は不要です。新規クライアントは最新ドキュメントに従ってください。「権限と同意」を参照。

クライアント作成は POST /api/v1/developer/clients を呼び、JSON 本文に clientType、requiredScopes / optionalScopes、scopeReasons、任意の dataDeletionUri、privacyPolicyUri を渡します。既存クライアントの更新は PUT /api/v1/developer/clients/{clientId}（権限と理由を更新できます）。

次のステップ：同ディレクトリの「連携の概要」を読み、「認可コードと PKCE」を実装してください。