Owner Claim

Returns a minimal public summary of an owner claim so the recipient can confirm they are looking at the right request before logging in.

Authentication

This endpoint is public (the user is not yet authenticated when they click the email link). The only credential is the claim token in the URL path.

Privacy

Anti-leak by design: the initiator email is masked (jo***@example.com), the owner email is never returned, and no internal IDs are exposed. Unknown / consumed tokens return a generic 404 (anti-oracle); responses are padded to a constant minimum latency.

Example

Code
curl https://api.faireplace.com/api/owner-claim/3f8b1c2d-...-9a0e

Response:

Code
{
  "initiator_email_partial": "jo***@example.com",
  "owner_display_name": "Jean Dupont",
  "expires_at": "2026-06-27T10:00:00Z"
}

Finalizes an owner claim: links owner.auth_user_id to the currently authenticated account and marks the claim session as consumed.

Authentication

Unlike the GET above, this endpoint requires authentication (Bearer JWT, PropertiesRead permission). The user must be logged in; the confirmation matches the authenticated account against the claim initiator. The token is still read from the URL path.

Body

The request body may be empty — the confirmation is derived from the JWT and the path token.

Example

Code
curl -X POST https://api.faireplace.com/api/owner-claim/3f8b1c2d-...-9a0e/confirm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

Code
{
  "owner_id": "550e8400-e29b-41d4-a716-446655440000",
  "claimed_at": "2026-06-20T14:30:00Z"
}

Starts an owner-claim workflow for the given owner_id. The backend generates a token, persists the claim session, and the targeted owner receives an email containing the confirmation link.

Authentication

This endpoint requires authentication (Bearer JWT, PropertiesWrite permission) — it modifies the account ↔ owner association. The initiator identity (auth user id + email) and tenant are taken from the JWT.

The claim TTL defaults to 7 days (168 hours).

Example

Code
curl -X POST https://api.faireplace.com/api/owners/550e8400-e29b-41d4-a716-446655440000/claim/start \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (201 Created):

Code
{
  "frontend_url": "https://app.faireplace.com/owner-claim/3f8b1c2d-...-9a0e",
  "owner_email": "[email protected]"
}