无法更新Tapkey Grant：请求返回400错误及权限限制问题

问题场景 #

调用Tapkey的/api/v1/Owners/{ownerAccountId}/Grants/{id}接口更新Grant对象时，返回400（Bad Request）错误，错误提示如下：

ErrorMessage: "每个锁和用户/卡片只能存在一个授权"（原英文提示："only one grant allowed per lock and user/card"）

原Grant对象信息 #

{
  "active": false,
  "boundCard": null,
  "boundCardId": null,
  "boundLock": {
    "targetType": "Lock",
    "id": "...",
    "clientRef": null,
    "physicalLockId": "...",
    "title": "Vorhängeschloss zum Testen",
    "description": null
  },
  "boundLockId": "...",
  "clientRef": null,
  "contact": {
    "email": "...",
    "ipUserName": "...",
    "id": "...",
    "clientRef": null,
    "ownerId": "...",
    "ipId": "tapkey",
    "comment": null,
    "isActive": true,
    "title": null,
    "ipUserId": null,
    "identifier": "..."
  },
  "contactId": "...",
  "credentialId": null,
  "customPayload": null,
  "id": "...",
  "keyLifetime": null,
  "mobileDeviceRef": null,
  "owner": null,
  "permissionDetails": null,
  "state": "Expired",
  "timeRestrictionIcal": null,
  "validBefore": "2023-03-04T23:00:00.000Z",
  "validFrom": "2023-03-03T23:00:00.000Z"
}

待更新的Grant对象信息 #

{
  "boundLockId": "...",
  "contactId": "",
  "timeRestrictionIcal": "BEGIN:VCALENDAR\nVERSION:2.0\nPRODID:http://localhost:3000\nBEGIN:VEVENT\nUID:20230301T010000Z5fa30d57-27b3-461f-973e-d46e91f56f86\nDTSTAMP:20230228T230000Z\nDTSTART;TZID=Europe/Berlin:20230303T230000\nDTEND;TZID=Europe/Berlin:20230304T230000\nEND:VEVENT\nBEGIN:VEVENT\nUID:20230502T000000Z5fa30d57-27b3-461f-973e-d46e91f56f86\nDTSTAMP:20230502T000000Z\nDTSTART;TZID=Europe/Berlin:20230505T000000\nDTEND;TZID=Europe/Berlin:20230507T000000\nEND:VEVENT\nEND:VCALENDAR",
  "validBefore": null,
  "validFrom": null
}

原因分析 #

Tapkey的权限规则明确：同一锁资源下，每个用户/卡片只能关联一个授权（Grant）。本次更新触发错误的核心原因：

1. 原Grant虽处于Expired状态，但系统仍将其计入该锁与对应用户的授权关联记录中，未自动清理。
2. 待更新的Grant将contactId设为空字符串，这种操作可能被系统判定为试图创建新的无用户关联授权，或破坏了原有锁-用户的唯一关联约束，触发校验逻辑。

解决办法 #

1. 删除过期Grant后再更新
   先调用Tapkey的删除Grant接口/api/v1/Owners/{ownerAccountId}/Grants/{id}，移除已过期的原Grant记录，清除锁与用户的关联后，再执行更新操作。
2. 避免直接置空contactId
   若需解除用户与锁的授权关联，优先通过删除Grant实现，而非将contactId设为空字符串——空值可能不符合接口参数规范，导致校验失败。
3. 校验锁-用户的授权唯一性
   检查该锁与目标用户是否存在其他有效或过期的Grant记录，确保同一组合下仅保留一条需要的Grant，再进行更新或创建操作。

内容的提问来源于stack exchange，提问作者Vlad Mashenko