API 密钥权限
API 密钥权限限制某个软件集成在密钥所属分组中可以执行的操作。密钥权限不代表个人身份，不授予其他分组的访问权，也不替代组织的 Rental 套餐。通过 launch_url 打开的人工操作，仍要求已登录且具备相应分组权限的 TrakarIA 用户。
每个系统应使用独立密钥，并且只授予实际会执行的操作。这样可以单独轮换或撤销某个集成，同时降低凭证泄露的影响。
每个公开 API 操作都会检查一个明确的权限。读取权限从不包含写入权限。在 API 与集成 中选择写入权限时，界面也会选择对应的读取权限（如存在）；选择附件提取时也会选择附件读取。这只是创建界面的便利行为，并不表示 API 权限之间存在隐含关系。
| 权限 | 允许的操作 | 公开路由 |
|---|---|---|
vehicles:read | 读取和对账密钥所属分组中的车辆。 | GET /v1/vehicles, GET /v1/vehicles/{vehicle_id} |
vehicles:write | 按外部系统的稳定 ID 创建或同步车辆。 | PUT /v1/vehicles/by-external/{external_id} |
rentals:read | 读取和对账 Rental 档案及已准备的检查。 | GET /v1/rentals, GET /v1/rentals/{rental_id}, GET /v1/inspections/{inspection_id} |
rentals:write | 创建、同步、更新或取消 Rental 档案。 | PUT /v1/rentals/by-external/{external_id}, PATCH /v1/rentals/{rental_id}, POST /v1/rentals/{rental_id}/cancel |
inspections:write | 准备或恢复交车/还车检查，并续期短期启动链接。该权限不能让 API 代替人员完成验证。 | POST /v1/rentals/{rental_id}/inspections, POST /v1/inspections/{inspection_id}/launch |
evidence:read | 列出并下载获授权的原始检查凭证，可单独下载或打包为 ZIP。 | GET /v1/inspections/{inspection_id}/evidence, GET /v1/evidence/{evidence_id}/content, GET /v1/inspections/{inspection_id}/evidence/archive, GET /v1/rentals/{rental_id}/evidence/archive |
attachments:read | 列出并下载由集成系统提供的私有文档。 | GET /v1/rentals/{rental_id}/attachments, GET /v1/attachments/{attachment_id}/content |
attachments:write | 向 Rental 档案上传私有文档。 | POST /v1/rentals/{rental_id}/attachments |
attachments:extract | 对已有的驾驶证附件启动计费提取。提取值仍须复核。 | POST /v1/attachments/{attachment_id}/extract |
reports:read | 查找、读取和下载交车/对比报告及 PDF。 | GET /v1/rentals/{rental_id}/report, GET /v1/rentals/{rental_id}/reports, GET /v1/reports/{report_id}, GET /v1/reports/{report_id}/pdf |
events:read | 对账 Webhook 中断期间遗漏的生命周期事件。 | GET /v1/events |
jobs:read | 查询异步操作的安全状态和结果，包括文档提取。 | GET /v1/jobs/{job_id} |
GET /v1/capabilities 需要有效且启用的密钥，但不要求其他操作权限。它返回当前可用的产品能力和限制，并不是密钥权限的完整列表。
Webhook 目标由已登录的分组管理员单独管理。events:read 只控制 GET /v1/events 对账；它不会创建目标，不授予管理界面访问权，也不能代替签名验证。
常见权限组合
Section titled “常见权限组合”| 集成需求 | 建议的最小权限 |
|---|---|
| 检查连接和商业功能 | 一把有效密钥，无需额外操作权限 |
| 同步车队和预订 | vehicles:read, vehicles:write, rentals:read, rentals:write |
| 准备交车和还车检查 | 再添加 inspections:write |
| 获取检查照片和最终报告 | 再添加 evidence:read, reports:read |
| 上传文档并提取驾驶证 | 再添加 attachments:read, attachments:write, attachments:extract, jobs:read |
| Webhook 中断后恢复事件 | 再添加 events:read |
| 实现完整 Rental 生命周期 | 选择所用场景对应的全部权限；未使用提取或附件功能时不要授予相关权限 |
每个操作的准确要求在 API 参考中标为 Required permission。
排查 403
Section titled “排查 403”有效密钥缺少所需权限时，API 返回 403 和 INSUFFICIENT_SCOPE，缺少的权限位于 errors[0].meta.required。只有集成确实需要该操作时，才应将权限添加到替换密钥。
403 也可能表示资源不属于该分组、组织或功能不可用，或者套餐不包含此操作。授予所有权限不会绕过这些检查。参阅身份验证与访问控制和同步规则与错误处理。