snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/ja/developers/extend/oauth.mdx

@@ -0,0 +1,189 @@
+---
+title: OAuth
+icon: key
+description: PKCE を用いた認可コードフロー、およびサーバー間アクセス向けのクライアントクレデンシャル。
+---
+
+Twenty は、ユーザー向けアプリでは認可コード + PKCE、サーバー間アクセスではクライアントクレデンシャルを用いた OAuth 2.0 を実装しています。 クライアントは [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) に従って動的に登録され、ダッシュボードでの手動セットアップは不要です。
+
+## OAuth を使用するタイミング
+
+| シナリオ                   | 認証方法                                                                         |
+| ---------------------- | ---------------------------------------------------------------------------- |
+| 社内向けスクリプト、自動化          | [API キー](/l/ja/developers/extend/api#authentication)                              |
+| ユーザーの代理として動作する外部アプリ    | **OAuth — 認可コード**                                                            |
+| サーバー間、ユーザーコンテキストなし     | **OAuth — クライアントクレデンシャル**                                                    |
+| UI 拡張機能を備えた Twenty アプリ | [アプリ](/l/ja/developers/extend/apps/getting-started/quick-start)（OAuth は自動で処理されます） |
+
+## クライアントを登録
+
+Twenty は [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) に準拠した**動的クライアント登録**をサポートします。 手動セットアップは不要—プログラムで登録します:
+
+```bash
+POST /oauth/register
+Content-Type: application/json
+
+{
+  "client_name": "My Integration",
+  "redirect_uris": ["https://myapp.com/callback"],
+  "grant_types": ["authorization_code"],
+  "token_endpoint_auth_method": "client_secret_post"
+}
+```
+
+**レスポンス:**
+
+```json
+{
+  "client_id": "abc123",
+  "client_secret": "secret456",
+  "client_name": "My Integration",
+  "redirect_uris": ["https://myapp.com/callback"]
+}
+```
+
+<Warning>
+`client_secret` は安全に保管してください—後から再取得することはできません。
+</Warning>
+
+## スコープ
+
+| スコープ      | アクセス                                     |
+| --------- | ---------------------------------------- |
+| `api`     | Core および Metadata API への読み取り/書き込みのフルアクセス |
+| `profile` | 認証済みユーザーのプロフィール情報を読み取る                   |
+
+スコープはスペース区切りの文字列で指定します: `scope=api profile`
+
+## 認可コードフロー
+
+アプリが Twenty ユーザーの代理として動作する場合にこのフローを使用します。
+
+### 1. ユーザーを認可にリダイレクト
+
+```
+GET /oauth/authorize?
+  client_id=YOUR_CLIENT_ID&
+  response_type=code&
+  redirect_uri=https://myapp.com/callback&
+  scope=api&
+  state=random_state_value&
+  code_challenge=CHALLENGE&
+  code_challenge_method=S256
+```
+
+| パラメーター                  | 必須  | 説明                                                |
+| ----------------------- | --- | ------------------------------------------------- |
+| `client_id`             | はい  | 登録済みのクライアント ID                                    |
+| `response_type`         | はい  | `code` である必要があります                                 |
+| `redirect_uri`          | はい  | 登録済みのリダイレクト URI と一致している必要があります                    |
+| `scope`                 | いいえ | スペース区切りのスコープ（既定は `api`）                           |
+| `state`                 | 推奨  | CSRF 攻撃を防ぐためのランダムな文字列                             |
+| `code_challenge`        | 推奨  | PKCE チャレンジ（ベリファイアの SHA-256 ハッシュを base64url エンコード） |
+| `code_challenge_method` | 推奨  | PKCE 使用時は `S256` である必要があります                       |
+
+ユーザーに同意画面が表示され、アクセスを許可または拒否します。
+
+### 2. コールバックを処理
+
+認可後、Twenty はあなたの `redirect_uri` にリダイレクトします:
+
+```
+https://myapp.com/callback?code=AUTH_CODE&state=random_state_value
+```
+
+`state` が送信した値と一致することを確認します。
+
+### 3. コードをトークンに交換
+
+```bash
+POST /oauth/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=authorization_code&
+code=AUTH_CODE&
+redirect_uri=https://myapp.com/callback&
+client_id=YOUR_CLIENT_ID&
+client_secret=YOUR_CLIENT_SECRET&
+code_verifier=YOUR_PKCE_VERIFIER
+```
+
+**レスポンス:**
+
+```json
+{
+  "access_token": "eyJhbG...",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "refresh_token": "dGhpcyBpcyBh..."
+}
+```
+
+### 4. アクセストークンを使用
+
+```bash
+GET /rest/companies
+Authorization: Bearer ACCESS_TOKEN
+```
+
+### 5. 期限切れ時にリフレッシュ
+
+```bash
+POST /oauth/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=refresh_token&
+refresh_token=YOUR_REFRESH_TOKEN&
+client_id=YOUR_CLIENT_ID&
+client_secret=YOUR_CLIENT_SECRET
+```
+
+## クライアントクレデンシャルフロー
+
+ユーザー操作のないサーバー間統合向け:
+
+```bash
+POST /oauth/token
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=client_credentials&
+client_id=YOUR_CLIENT_ID&
+client_secret=YOUR_CLIENT_SECRET&
+scope=api
+```
+
+返されるトークンは特定のユーザーに紐づかないワークスペースレベルのアクセス権を持ちます。
+
+## サーバーディスカバリー
+
+Twenty は標準のディスカバリーエンドポイントで OAuth 設定を公開しています:
+
+```
+GET /.well-known/oauth-authorization-server
+```
+
+これにより、すべてのエンドポイント、対応するグラントタイプ、スコープ、および機能が返されます—汎用的な OAuth クライアントを構築するのに役立ちます。
+
+## API エンドポイント概要
+
+| エンドポイント                                   | 目的                |
+| ----------------------------------------- | ----------------- |
+| `/.well-known/oauth-authorization-server` | サーバーメタデータのディスカバリー |
+| `/oauth/register`                         | 動的クライアント登録        |
+| `/oauth/authorize`                        | ユーザー認可            |
+| `/oauth/token`                            | トークンの交換とリフレッシュ    |
+
+| 環境         | ベース URL                  |
+| ---------- | ------------------------ |
+| **クラウド**   | `https://api.twenty.com` |
+| **セルフホスト** | `https://{your-domain}`  |
+
+## OAuth と API キー
+
+|                 | APIキー          | OAuth             |
+| --------------- | -------------- | ----------------- |
+| **セットアップ**      | 設定で生成          | クライアントを登録し、フローを実装 |
+| **ユーザーコンテキスト**  | なし（ワークスペースレベル） | 特定ユーザーの権限         |
+| **最適な用途**       | スクリプト、社内ツール    | 外部アプリ、マルチユーザー統合   |
+| **トークンローテーション** | 手動             | リフレッシュトークンにより自動   |
+| **スコープによるアクセス** | API へのフルアクセス   | スコープによりきめ細かな制御    |