Authentication

Every third-party request is gated by two things:

1. An Origin header that exactly matches a ThirdPartyOrigin record registered by the Homesoon admin team.
2. For user-scoped endpoints, a Bearer access token issued via POST /v1/third-party/refresh_tokens.

1. Register your origin

Contact the Homesoon admin team with:

• The exact Origin value your servers will send (e.g. https://partner.example.com).
• The list of permission groups you need (see Permission scopes, backed by the ThirdPartyPermission enum).
• An access level: VIEW or EDIT.

The admin will register you via the internal endpoint POST /v1/admin/partners/origins (handled by AdminThirdPartyOriginController).

2. Send the Origin header

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

Requests with an unregistered Origin get 401 Unauthorized. Requests to a path the origin was not granted access to get 403 Forbidden.

3. Refresh access tokens

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>"}'

Response:

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

Permission scopes

Permission	URL patterns
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