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. 获取访问令牌
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。
在文档中测试
- 打开 获取访问令牌, 点击 Try it。
- 输入
client_id和client_secret,grant_type保持为client_credentials,然后发送请求。 - 复制响应中的
access_token。 - 打开 API 参考 中的任意接口页面,将令牌粘贴到 Authorization 字段并发送请求。
POST/PUT
会更改真实的充电限值,如果不打算应用更改,请使用只读客户端进行测试。
轮换和撤销凭据
- 轮换:创建新客户端,将集成切换到新客户端,然后撤销旧客户端。
- 撤销:在仪表板中客户端旁边操作。撤销立即生效:该客户端已发放的令牌 在下一次请求时即失效。
- 已过期 的临时客户端同样会立即失效。

