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

---
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 へのフルアクセス   | スコープによりきめ細かな制御    |