認証

サードパーティからのリクエストは、次の 2 つによって保護されています。

1. Homesoon 管理チームが登録した ThirdPartyOrigin レコードと完全に一致する Origin ヘッダー。
2. ユーザースコープのエンドポイントの場合は、 POST /v1/third-party/refresh_tokens で発行した Bearer アクセストークン。

1. Origin を登録する

次の情報を添えて Homesoon 管理チームにご連絡ください。

• 自社サーバーが送信する Origin の正確な値（例: https://partner.example.com）。
• 必要なパーミッショングループの一覧（パーミッションスコープ を参照。 バックエンドの ThirdPartyPermission enum に対応しています）。
• アクセスレベル: VIEW または EDIT。

管理チームが内部エンドポイント POST /v1/admin/partners/origins （AdminThirdPartyOriginController が処理）で登録を行います。

2. Origin ヘッダーを送信する

curl -X GET https://api.homesoon.jp/api/v1/third-party/workspaces \
  -H "Origin: https://partner.example.com" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

未登録の Origin からのリクエストは 401 Unauthorized になります。 その Origin に許可されていないパスへのリクエストは 403 Forbidden になります。

3. アクセストークンを更新する

curl -X POST https://api.homesoon.jp/api/v1/third-party/refresh_tokens \
  -H "Origin: https://partner.example.com" \
  -H "Content-Type: application/json" \
  -d '{"refreshToken":"<your refresh token>"}'

レスポンス:

{
  "status": "success",
  "data": {
    "accessToken": "eyJhbGciOi...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "refreshToken": "..."
  }
}

パーミッションスコープ

パーミッション	URL パターン
AUTH	/v1/third-party/refresh_tokens
PROFILE	/v1/third-party/company/profile/my-info, /v1/third-party/admin-company/profile/*
SUPERVISOR	/v1/third-party/supervisors, /v1/third-party/workspaces/*/supervisors, /v1/third-party/moderators, .../*/moderators
WORKSPACE	/v1/third-party/workspaces
CONSTRUCTION	/v1/third-party/workspaces/*/constructions
TASK	/v1/third-party/admin-company/constructions/*/tasks, /v1/third-party/constructions/*/tasks/*
APPOINTMENT	/v1/third-party/workspaces/*/appointments
RECORD	/v1/third-party/workspaces/*/shabelabo-records, /v1/third-party/shabelabo-records/javis/update-metadata