概要

App を Workspace にインストールするには OAuth 2.0 Authorization Code Flow を使用します。Workspace の管理者がスコープを承認すると、App はその Workspace のデータにアクセスできるようになります。

フロー

1. アプリ → /authorize にリダイレクト（client_id, redirect_uri, scope, state）
2. Speria → ユーザー認証 → Workspace 選択 → スコープ確認画面
3. 管理者 → スコープを承認
4. Speria → redirect_uri にリダイレクト（code, state）
5. アプリ → POST /oauth/token（code + client_secret）
6. Speria → workspace_id + scope を返却

実装手順

1. 認可リクエスト

ユーザーを Speria の認可エンドポイントにリダイレクトします。

GET https://id.speria.jp/authorize

パラメータ	必須	説明
`response_type`	Yes	`code` を指定
`client_id`	Yes	App の client_id
`redirect_uri`	Yes	App に登録済みのコールバック URL
`scope`	Yes	要求するスコープ（スペース区切り）
`state`	Yes	CSRF 防止用のランダム文字列
`workspace_hint`	No	Workspace ID を指定すると Workspace 選択をスキップ

scope は App の requested_scopes の範囲内である必要があります。超過する場合は invalid_scope エラーが返されます。

2. コールバック

管理者がスコープを承認すると、redirect_uri に code と state が返されます。

https://your-app.example.com/callback?code=xxx&state=zzz

state がリクエスト時の値と一致することを検証してください。

3. トークン交換

code を client_secret とともに送信し、インストール情報を取得します。

POST https://api.speria.jp/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=xxx
&client_id=your_client_id
&client_secret=your_client_secret
&redirect_uri=https://your-app.example.com/callback

レスポンス:

{
  "workspace_id": "01abc...",
  "scope": "customer_visits:read transcripts:read"
}

scope は付与されたスコープをスペース区切りで並べた文字列です（OAuth 2.0 / RFC 6749 §5.1 準拠）。workspace_id と scope を保存してください。これがインストールの事実を表します。

インストールの開始方法

App 側から開始

アプリに「Speria に接続」ボタンを配置し、クリック時に state を生成して /authorize にリダイレクトします。

developer アプリから開始

developer アプリの App 設定で install_landing_url を設定すると、developer アプリからインストールフローを開始できます。Workspace 管理者がこの URL にリダイレクトされ、アプリ側で state を生成して /authorize に進みます。

セキュリティ

state パラメータは必須です（CSRF 防止）
authorization_code は短命（数分）で一度限り使用可能です
redirect_uri は App に登録済みの URL と完全一致で検証されます
client_secret はサーバーサイドでのみ使用してください

App インストール（OAuth 2.0）

概要

フロー