--- title: クライアントを接続する description: パブリッククライアントを登録し、PKCE で利用者の認可を受け、コードをトークンに交換し、更新し続けます。アクセストークンの有効期間は 5 分です。 --- Taylorz CRM は PKCE を用いた OAuth 2.0 認可コードグラントでトークンを発行します。すべてのクライアントはパブリックです。シークレットを持たず、トークンエンドポイント認証方式は `none` です。 グラントは同意の時点で 1 つの組織に紐づき、トークンは 1 つのリソースのみを指名します。Web アプリケーションで利用者が見ている組織を切り替えても、既存のトークンの対象は変わりません。 ## 1. クライアントを登録する 登録には**組織の owner または admin のセッション**が必要で、クライアントはそのセッションがアクティブにしている組織に紐づきます。匿名登録と動的クライアント登録はいずれも無効なので、クライアントが自分自身を登録することはできません。 これ専用の画面はまだありません。ワークスペースの管理者でない場合は、管理者にクライアントの登録を依頼し、`client_id` を受け取ってください。 登録が指定する内容です。 ```json { "application_type": "native", "client_name": "Your integration", "grant_types": ["authorization_code", "refresh_token"], "redirect_uris": ["http://localhost:9876/callback"], "response_types": ["code"], "scope": "offline_access api.access records.read", "token_endpoint_auth_method": "none" } ``` `application_type` は重要です。ループバックのリダイレクトはネイティブクライアントのものであり、Web クライアントには拒否されます。リフレッシュトークンが必要なら `offline_access` を要求してください。手順 4 の理由により、実際に必要です。 ## 2. 利用者を認可画面へ送る verifier を生成し、その challenge を導出して、利用者を認可エンドポイントへ送ります。サインインと同意はそこで行われます。 ``` GET /api/auth/oauth2/authorize ?client_id= &response_type=code &redirect_uri=<登録済みのいずれかの uri> &resource=<接続先のリソース> &scope=offline_access+api.access+records.read &code_challenge= &code_challenge_method=S256 &state=<任意の値> ``` `resource` は必須で、トークンの用途を指名します。REST リソースか、MCP かです。トークンは 1 つのリソースに対応するため、両方が必要なクライアントは 2 回認可を受けます。 レスポンスは `code` と指定した `state` を付けて `redirect_uri` にリダイレクトします。 ## 3. コードを交換する ``` POST /api/auth/oauth2/token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code &client_id= &code= &code_verifier=<手順 2 の verifier> &redirect_uri=<同じ uri> &resource=<同じリソース> ``` `access_token` が返り、`offline_access` を要求していれば `refresh_token` も返ります。 アクセストークンを Bearer トークンとして API を呼び出します。 ``` GET /api/v1/objects Authorization: Bearer ``` Bearer のみです。DPoP にバインドされたトークン、すなわち `cnf` クレームを持つトークンは拒否されます。 ## 4. 頻繁に更新する **アクセストークンの有効期間は 5 分です。** 更新処理は後回しにできる例外ではなく、動作するクライアントの一部です。リフレッシュトークンを保持し、呼び出しが `401` を返す前または返した時点で交換してください。 ``` POST /api/auth/oauth2/token Content-Type: application/x-www-form-urlencoded grant_type=refresh_token &client_id= &refresh_token= &resource=<同じリソース> ``` 更新には、付与された接続スコープと、組織のモジュールが有効であることの両方が必要です。どちらかが失われていれば、暗黙に機能縮小されるのではなく更新が拒否されます。 ## 5. 不要になったら失効させる ``` POST /api/auth/oauth2/revoke ``` トークンを失効させるとその背後のグラントも失効するため、すでに発行済みのトークンは残り 5 分を待たずに直ちに使えなくなります。 ## ディスカバリ プロバイダは `/.well-known/oauth-authorization-server/api/auth` にメタデータを公開します。エンドポイントはハードコードせずそこから読み取ってください。この文書はサポートするトークンエンドポイント認証方式として `none` を広告しており、これがパブリッククライアントの使うものです。