跳转到主要内容

OAuth 2.0(客户端凭证模式)

Energy Management API 使用 OAuth 2.0 client_credentials 流程。 除 GET /health 和 POST /oauth/token 外,所有端点均需要 Bearer 令牌:

1. 创建凭据

你组织中的任何用户都可以在 RiDERgy 仪表板 中创建 OAuth 客户端凭据: 打开 我的账户,进入 OAuth Clients,然后选择 创建新客户端。 RiDERgy 需要先为你的组织启用 Energy Management API;未启用时,请求会返回 403 FEATURE_NOT_ENABLED。
  • 客户端 ID(emcl_...):不是机密,会一直显示在仪表板中。
  • 客户端密钥(emcs_...):仅在创建时显示 一次。请立即保存到密码管理器 或密钥保管库。RiDERgy 无法再次显示;如果丢失,请创建新客户端并撤销旧客户端。
  • 只选择集成所需的 scope。新客户端默认为只读。
  • 客户端属于你的 组织,而不是创建它的人,因此该人员离职后仍可继续使用。
  • RiDERgy 不发放 API 密钥。带有 x-api-key 请求头的请求会被 401 拒绝; 请始终按下文使用 Bearer 令牌。
还没有仪表板登录? 在你的组织入驻期间,RiDERgy 可以发放一个 7 天后到期的 临时 客户端。你会通过两个不同的渠道分别收到客户端 ID 和密钥。获得仪表板 登录后,请创建你自己的客户端,并请 RiDERgy 撤销临时客户端。

2. 获取访问令牌

令牌在 3600 秒(1 小时)后过期。请在当前令牌到期前请求新令牌。 您也可以通过 Authorization: Basic base64(client_id:client_secret) 并在请求正文中 包含 grant_type=client_credentials 来传递凭据(RFC 6749)。

3. 使用令牌

在每个请求中以 Authorization: Bearer <token> 传递令牌:
  • 您的租户嵌入在令牌中,无法伪造——一个租户的凭据无法访问另一个租户的数据。
  • 过期或无效的令牌返回 401 UNAUTHORIZED。
  • 缺少所需 scope 的令牌返回 403 INSUFFICIENT_SCOPE。

Scopes

令牌携带的 scope 控制可访问的端点: 对需要某个 scope 但令牌不具备该 scope 的端点发出请求时,将返回 403 INSUFFICIENT_SCOPE。

在文档中测试

  1. 打开 获取访问令牌, 点击 Try it。
  2. 输入 client_id 和 client_secret,grant_type 保持为 client_credentials,然后发送请求。
  3. 复制响应中的 access_token。
  4. 打开 API 参考 中的任意接口页面,将令牌粘贴到 Authorization 字段并发送请求。
文档中的请求发送到 线上生产 API,且只能访问你组织的站点。POST/PUT 会更改真实的充电限值,如果不打算应用更改,请使用只读客户端进行测试。

轮换和撤销凭据

  • 轮换:创建新客户端,将集成切换到新客户端,然后撤销旧客户端。
  • 撤销:在仪表板中客户端旁边操作。撤销立即生效:该客户端已发放的令牌 在下一次请求时即失效。
  • 已过期 的临时客户端同样会立即失效。