データアクセス（Client Credentials）

概要

インストール済み Workspace のデータにアクセスするには、Client Credentials で短命トークン（app_credential）を発行し、API リクエストに使用します。

フロー

1. アプリ → POST /oauth/token（client_credentials + workspace_id）
2. Speria → app_credential（短命トークン、TTL 1時間）を返却
3. アプリ → API リクエスト（Authorization: Bearer {app_credential}）
4. Speria → スコープ内のデータを返却

実装手順

1. トークン発行

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

grant_type=client_credentials
&client_id=your_client_id
&client_secret=your_client_secret
&workspace_id=01abc...

レスポンス:

{
  "access_token": "speria_app_xxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "workspaces:read customer_visits:read"
}

scope は発行されたトークンに付与されたスコープをスペース区切りで並べた文字列です（インストール時に承認された granted_scopes に基づく / RFC 6749 §5.1 準拠）。

2. API リクエスト

発行されたトークンを Authorization ヘッダーに設定して API にアクセスします。

GET https://api.speria.jp/v1/workspaces/{workspace_id}/customer_visits
Authorization: Bearer speria_app_xxxxxxxx

トークンの仕様

ベストプラクティス

トークンのキャッシュ

app_credential は Workspace ごとにキャッシュし、有効期限前に再発行してください。リクエストのたびに新しいトークンを発行する必要はありません。

エラーハンドリング

API が 401 Unauthorized を返した場合、トークンが期限切れの可能性があります。新しいトークンを発行してリトライしてください。

client_secret の安全な管理

• client_secret はサーバーサイドでのみ使用してください
• 環境変数やシークレット管理サービスで保管してください
• コードやログに含めないでください
• 漏洩が疑われる場合は developer アプリで即座にローテーションできます（最大 2 本の同時有効化に対応）

インストール状況の確認

GET /v1/apps/{client_id}/installations で App のインストール状況を確認できます（client_secret 認証、カーソルページネーション）。自身のレコードと定期的に突き合わせて、アンインストールを検知してください。