​
Scope 目录

UTMOS 使用 Casbin 的租户域授权模型。对外文档里的“scope”对应 Casbin 的 object:action 组合，而不是旧式字符串 scope。

​
Open Platform 权限

权限授予的能力涉及接口
open:command:create受理云端到设备命令POST /api/v1/open/downlink/commands
open:command:read查询已受理命令GET /api/v1/open/downlink/commands/{command_id}
open:object:create为租户授权对象生成上传或下载预签名 URLPOST /api/v1/open/objects/presign
open:object-config:create创建租户对象存储凭证或资源策略POST /api/v1/open/objects/credentials, POST /api/v1/open/objects/resources
open:object-config:read查询租户对象存储配置GET /api/v1/open/objects/credentials, GET /api/v1/open/objects/resources
open:object-config:update更新或轮换租户对象存储配置PUT /api/v1/open/objects/credentials/{credential_id}, PUT /api/v1/open/objects/resources/{resource_id}
open:callback:create创建回调 endpoint 或订阅POST /api/v1/open/callbacks/endpoints, POST /api/v1/open/callbacks/endpoints/{endpoint_id}/subscriptions
open:callback:read查询回调 endpoint 或订阅GET /api/v1/open/callbacks/endpoints
open:callback:update更新或轮换回调 endpointPUT /api/v1/open/callbacks/endpoints/{endpoint_id}
open:callback:disable删除回调订阅DELETE /api/v1/open/callbacks/endpoints/{endpoint_id}/subscriptions/{subscription_id}
open:device-request:read查询设备到云端请求GET /api/v1/open/device-requests, GET /api/v1/open/device-requests/{request_id}
open:device-request:create回复设备到云端请求POST /api/v1/open/device-requests/{request_id}/reply

​
建议角色

Role适用场景常见权限
tenant_admin租户管理员管理本租户 credential、ACL、对象存储、回调和 NATS 配置
integration_operator业务系统接入open:command:create、open:command:read、open:object:create、open:device-request:read
integration_reader只读集成查询命令和设备请求，不创建命令

​
授权模型

租户、身份、scope 和业务事实的关系如下：
概念来源职责
Tenantauthenticated credential binding数据隔离边界
CredentialX-Api-Id调用方身份
Role BindingCasbin g policy把 client_id 绑定到租户域内角色
ScopeCasbin object:action描述调用方在租户内能做什么
Business Ownershipcommand/object/callback facts持久化业务事实归属
Casbin 请求模型为： 
sub = client_id
dom = tenant_id
obj = object
act = action
命令受理检查： 
Enforce(client_id, tenant_id, "open:command", "create")
对象预签名检查： 
Enforce(client_id, tenant_id, "open:object", "create")
对象存储配置检查使用 open:object-config，回调配置检查使用 open:callback。 tenant_id 必须来自认证后的 credential binding，不能由请求体声明或覆盖。后续查询、回调、适配器执行和对象访问都必须使用业务事实中的 tenant_id 作为边界，不能只依赖 command_id、resource_id 或其他全局 ID。

​
鉴权失败时

调用没有权限的接口会返回： 
{
  "code": "FORBIDDEN",
  "message": "authorization denied",
  "request_id": "req_001"
}
排查：
  • 确认 X-Api-Id 是预期的 client credential。
  • 确认 credential 绑定到了正确的 tenant_id。
  • 确认该 client_id 在租户域内拥有对应 Casbin policy 或 role binding。
更多错误码见 错误模型。