クライアントを接続する

パブリッククライアントを登録し、PKCE で利用者の認可を受け、コードをトークンに交換し、更新し続けます。アクセストークンの有効期間は 5 分です。

Taylorz CRM は PKCE を用いた OAuth 2.0 認可コードグラントでトークンを発行します。すべてのクライアントはパブリックです。シークレットを持たず、トークンエンドポイント認証方式は none です。

グラントは同意の時点で 1 つの組織に紐づき、トークンは 1 つのリソースのみを指名します。Web アプリケーションで利用者が見ている組織を切り替えても、既存のトークンの対象は変わりません。

1. クライアントを登録する

登録には組織の owner または admin のセッションが必要で、クライアントはそのセッションがアクティブにしている組織に紐づきます。匿名登録と動的クライアント登録はいずれも無効なので、クライアントが自分自身を登録することはできません。

これ専用の画面はまだありません。ワークスペースの管理者でない場合は、管理者にクライアントの登録を依頼し、client_id を受け取ってください。

登録が指定する内容です。

{
  "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=<client_id>
  &response_type=code
  &redirect_uri=<登録済みのいずれかの uri>
  &resource=<接続先のリソース>
  &scope=offline_access+api.access+records.read
  &code_challenge=<BASE64URL(SHA256(verifier))>
  &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=<client_id>
&code=<code>
&code_verifier=<手順 2 の verifier>
&redirect_uri=<同じ uri>
&resource=<同じリソース>

access_token が返り、offline_access を要求していれば refresh_token も返ります。

アクセストークンを Bearer トークンとして API を呼び出します。

GET /api/v1/objects
Authorization: Bearer <access_token>

Bearer のみです。DPoP にバインドされたトークン、すなわち cnf クレームを持つトークンは拒否されます。

4. 頻繁に更新する

アクセストークンの有効期間は 5 分です。 更新処理は後回しにできる例外ではなく、動作するクライアントの一部です。リフレッシュトークンを保持し、呼び出しが 401 を返す前または返した時点で交換してください。

POST /api/auth/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=<client_id>
&refresh_token=<refresh_token>
&resource=<同じリソース>

更新には、付与された接続スコープと、組織のモジュールが有効であることの両方が必要です。どちらかが失われていれば、暗黙に機能縮小されるのではなく更新が拒否されます。

5. 不要になったら失効させる

POST /api/auth/oauth2/revoke

トークンを失効させるとその背後のグラントも失効するため、すでに発行済みのトークンは残り 5 分を待たずに直ちに使えなくなります。

ディスカバリ

プロバイダは /.well-known/oauth-authorization-server/api/auth にメタデータを公開します。エンドポイントはハードコードせずそこから読み取ってください。この文書はサポートするトークンエンドポイント認証方式として none を広告しており、これがパブリッククライアントの使うものです。