Skip to content
StraventaDocs

Transfer the merchant_owner role to another active member (TOTP-gated)

Atomic owner flip in a single transaction — assigns `merchant_owner` to the target member and revokes it from the caller, then demotes the caller to `tenant_admin` so they retain administrative access (minus owner-only operations). Notifies the previous owner via outbox email. Caller must hold `tenant.team.transfer`. Phase3 / T014. Phase 8 (AC-41.7): TOTP step-up is mandatory — the caller must have a confirmed TOTP enrollment and supply a valid `totp_code`. Two audit events are emitted in the same tx: `team.member.ownership_transferred` and `team.member.owner_demoted_to_admin`.

POST
/v1/admin/team/{memberId}/transfer-ownership

Atomic owner flip in a single transaction — assigns merchant_owner to the target member and revokes it from the caller, then demotes the caller to tenant_admin so they retain administrative access (minus owner-only operations). Notifies the previous owner via outbox email. Caller must hold tenant.team.transfer. Phase3 / T014. Phase 8 (AC-41.7): TOTP step-up is mandatory — the caller must have a confirmed TOTP enrollment and supply a valid totp_code. Two audit events are emitted in the same tx: team.member.ownership_transferred and team.member.owner_demoted_to_admin.

Authorization

bearerAuth
AuthorizationBearer <token>

JWT Bearer access token. Clock skew tolerance is ±60 seconds.

In: header

Path Parameters

memberId*string

Membership UUID (NOT user_id) — server resolves user via memberships lookup.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/admin/team/497f6eca-6276-4993-bfeb-53cbbbba6f08/transfer-ownership" \  -H "Content-Type: application/json" \  -d '{    "totp_code": "string"  }'
{
  "transferred": true,
  "new_owner_membership": "e90a6a0c-e23f-4cc0-9a2f-d6686e0f7d74"
}
{
  "error": "validation_failed",
  "message": "request body is invalid",
  "request_id": "string"
}
{
  "error": "validation_failed",
  "message": "request body is invalid",
  "request_id": "string"
}
{
  "error": "validation_failed",
  "message": "request body is invalid",
  "request_id": "string"
}
{
  "error": "not_found",
  "message": "the requested resource was not found",
  "request_id": "req_01abc125"
}

Was this page helpful?