身份验证
每个 /v1 请求都需要经过身份验证。从您自己的系统发起请求时,请使用以 Bearer 令牌形式发送的个人访问令牌(PAT)进行身份验证:
Authorization: Bearer waafir_pat_…在附加功能 → 配置下签发、限制和撤销令牌。个人访问令牌指南介绍了签发、有效期(默认 90 天,最长 365 天)、一次性显示和撤销。这些规则同样适用于平台 API。本页介绍的是您持有令牌后它能做什么。
个人访问令牌以签发者本人的身份在其所属组织内执行操作。任何 URL 或请求体中都没有组织参数,因为令牌本身已经确定了组织。
三项令牌检查
经令牌验证的请求必须通过以下三项检查(以及其他检查)。组织安全策略和端点自身的检查也可能拒绝请求(参见下文)。三项检查中有两项拥有各自专属的错误码。角色拒绝可能返回 FORBIDDEN,而其他拒绝也会使用该错误码,因此请结合端点的要求来解读错误码。
| 检查 | 问题 | 拒绝 |
|---|---|---|
| 令牌权限范围 | 令牌的权限范围是否涵盖该端点的操作? | PAT_SCOPE_INSUFFICIENT 403 |
| 角色 | 调用者是否拥有该端点所要求的角色? | FORBIDDEN 403,或 PAT_ROLE_CEILING 403 |
| 数据室 | 对于限定于数据室的令牌,该数据室是否在其列表中? | PAT_DATAROOM_SCOPE 403 |
令牌权限范围
每个令牌带有一个权限范围:read、write 或 admin,权限依次递增。较高的权限范围包含其下所有权限。
默认情况下,端点所需的权限范围由其 HTTP 方法决定:
GET、HEAD和OPTIONS需要read。- 其他所有方法(
POST、PATCH、PUT、DELETE)需要write。
有些端点声明了不同的权限范围。常见情况是只执行查询的 POST,它只需要 read。端点参考显示了每个端点实际要求的权限范围,因此请在那里查看,而不要根据方法推断。
所需角色与角色上限
权限范围说明的是令牌可以做什么。端点的所需角色说明的是人员必须具备什么身份。许多 /v1 端点要求交易团队身份(组织所有者、管理员或成员)。对团队和访问授权等的更改,要求所有者或管理员身份。投资者和其他访客不具备交易团队角色,因此交易团队端点会拒绝他们。另一些端点在身份验证层不声明角色门槛,而是在端点内部检查访问权限。例如,投资组合监控路由会检查监控附加功能以及调用者的监控访问权限。端点参考显示了每个端点的角色门槛。在未声明角色门槛的情况下,端点本身仍可能拒绝请求。
令牌还会记录其签发者在签发时的角色,作为上限。Waafir 采用的角色是签发者当前角色与该上限中较低的一个。之后被提升为管理员的成员,通过此前签发的令牌操作时仍以成员身份行事;如需使用新角色,请签发新令牌。角色被降低的人员会立即失去相应权限,无论令牌记录的是什么。上述任一权限不足的情况都会以 403 拒绝,错误码为 FORBIDDEN 或 PAT_ROLE_CEILING。
限定于数据室的令牌
签发时选择了特定数据室(而不是所有数据室)的令牌,只能访问这些数据室。指定任何其他数据室的请求都会以 PAT_DATAROOM_SCOPE 被拒绝。一些组织范围的端点会以同一错误码直接拒绝受限令牌,因为其返回结果涉及该令牌无法看到的数据室。对于这些端点,请使用不受限的令牌。GET /api/v1/session 接受这两种令牌。
您可能遇到的其他拒绝
401 UNAUTHORIZED:缺少Authorization请求头,或令牌未知、已过期或已被撤销。- 访问其他组织的资源时返回
404。属于其他组织的 ID 会被视为不存在,因此不会确认其是否存在。 - 受限文件不适用所有者/管理员的权限覆盖。在应用中,组织所有者或管理员可以看到每个受限文件。令牌则不然:只有当令牌所有者创建了某个受限文件或持有对它的授权时,令牌才能访问该文件。如果请求指定了令牌无法读取的文件,得到的响应与文件不存在时相同(对于
/api/v1/grants,返回指明该文件的400,或针对授权返回404),并附带一条消息说明其“not found, or not readable by this credential”,因此响应绝不会确认该文件存在。 - 组织安全策略。如果您的组织设置了 IP 允许列表,来自列表之外的请求会返回
IP_BLOCKED。双因素认证强制要求可能会返回MFA_SETUP_REQUIRED或MFA_CHALLENGE_REQUIRED。 429 RATE_LIMITED。某些端点为每个身份声明了每分钟的上限,该上限会显示在端点上。其余端点使用平台默认值。请退避后重试。
错误码页面列出了已知错误码及其含义。