OAuth

endpoint URL、supported grant、scope、response type、PKCE method、token authentication method は discovery metadata を source of truth にします。

GET /.well-known/oauth-authorization-server
GET /.well-known/openid-configuration

browser・installed client

public client は PKCE S256 付き Authorization Code を使います。high-entropy な code_verifier を毎回生成し、authorization 時に S256 challenge を送り、return 時に state を検証し、discovered token endpoint で code を交換します。secret を保持できない software に client secret を入れないでください。

pre-register されていない client では dynamic client registration を使います。正確な redirect URI を登録し、一致しない redirect を拒否します。必要最小限の scope を要求してください。read には read、mutation には write、MCP server には mcp、user 不在で refresh が必要な場合だけ offline_access を使います。

OpenID Connect

authenticated profile が必要なら discovered userinfo endpoint を使います。email address から identity や workspace authorization を推測しません。access token は API call を authorize し、ID・userinfo data は OpenID Connect contract に従って signed-in user を識別します。

token lifecycle endpoint

authorization server は /oauth/* と /.well-known/* で、token 発行・refresh、userinfo、revocation、introspection、dynamic registration、authorization-server metadata を提供します。refresh token は rotate されます。refresh 成功ごとに保存 token を置き換え、reuse または invalid refresh response があれば reauthorize してください。

user が integration を切断したら credential を revoke します。introspection は必要に応じた trusted server-side validation 用です。public client が確認のためだけに別 party へ credential を渡さないでください。

MCP authorization

MCP client は https://mcp.epismo.ai/ が公開する protected-resource metadata から開始し、そこに示された authorization server をたどって mcp を要求します。MCP resource server と API authorization server は別 origin なので、一つの URL を仮定せず discovered audience・resource metadata に従います。