メインコンテンツへスキップ
Twenty は、ユーザー向けアプリでは認可コード + PKCE、サーバー間アクセスではクライアントクレデンシャルを用いた OAuth 2.0 を実装しています。 クライアントは RFC 7591 に従って動的に登録され、ダッシュボードでの手動セットアップは不要です。

​
OAuth を使用するタイミング

シナリオ認証方法
社内向けスクリプト、自動化API キー
ユーザーの代理として動作する外部アプリOAuth — 認可コード
サーバー間、ユーザーコンテキストなしOAuth — クライアントクレデンシャル
UI 拡張機能を備えた Twenty アプリアプリ（OAuth は自動で処理されます）

​
クライアントを登録

Twenty は RFC 7591 に準拠した動的クライアント登録をサポートします。 手動セットアップは不要—プログラムで登録します: 
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"
}
レスポンス: 
{
  "client_id": "abc123",
  "client_secret": "secret456",
  "client_name": "My Integration",
  "redirect_uris": ["https://myapp.com/callback"]
}
client_secret は安全に保管してください—後から再取得することはできません。

​
スコープ

スコープアクセス
apiCore および 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. コードをトークンに交換

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
レスポンス: 
{
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBh..."
}

​
4. アクセストークンを使用

GET /rest/companies
Authorization: Bearer ACCESS_TOKEN

​
5. 期限切れ時にリフレッシュ

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

​
クライアントクレデンシャルフロー

ユーザー操作のないサーバー間統合向け: 
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 へのフルアクセススコープによりきめ細かな制御