认证

rrweb Cloud 提供浏览器安全的公开写入密钥，以及拥有完整读写权限、功能更强大的私有 API 密钥。请选择与请求匹配的最小权限凭据，而不是到处放置私有密钥。

凭据	可运行位置	能力
公开写入密钥（public_key_rr_*）	浏览器或服务器	创建录制、摄取事件，并附加浏览器可见的元数据
私有 API 密钥（secret_key_rr_*）	仅限受信服务器	完整的读写权限，包括摄取、元数据、检索和预签名访问
预签名 URL/令牌	针对单个限定资源的不受信查看者	在过期前读取已签名的录制资源

公开写入密钥是浏览器摄取的推荐凭据。私有 API 密钥是供受信服务器使用的服务器机密，由于它既能读取也能写入录制数据，爆炸半径更大：绝不要在浏览器代码中暴露私有 API 密钥。 当不受信的查看者需要临时访问某个录制资源时，使用预签名 URL/令牌。

在 rrweb Cloud 仪表板中管理这两个 API 密钥。存储和使用指导参见 API 密钥。

认证 HTTP 请求

在 Authorization 请求头中以 Bearer 令牌的形式发送为操作选择的密钥；公开写入密钥可用于浏览器录制写入，私有 API 密钥既能执行这些写入也能执行所有其他操作，但只能在受信服务器上使用。

Authorization: Bearer public_key_rr_your_key

浏览器端的录制事件写入和元数据写入请使用浏览器安全的公开写入密钥。私有 API 密钥也可以执行这些写入，以及列出、检索、统计和生成预签名链接的请求，但只能在受信服务器上使用。生成的 API 参考为每个操作标注了其接受的认证方法。

Browser Client 认证

浏览器客户端在其 start() 配置中以 publicApiKey 的形式接受浏览器安全的公开写入密钥。

import { start } from '@rrweb/browser-client';

start({
  publicApiKey: 'public_key_rr_your_key',
});

设置和录制器选项参见浏览器客户端文档。

WebSocket 认证

由于浏览器 WebSocket 连接无法设置自定义 Authorization 请求头，浏览器客户端会在 WebSocket 升级期间将公开写入密钥放入 token 查询参数中。

const recordingId = '550e8400-e29b-41d4-a716-446655440000';
const publicWriteKey = 'public_key_rr_your_key';
const url = new URL(`wss://api.rrweb.com/recordings/${recordingId}/events/ws`);
url.searchParams.set('token', publicWriteKey);

const socket = new WebSocket(url);

不要在 WebSocket URL 或任何其他浏览器代码中放置私有 API 密钥。

预签名访问

受信服务器使用其私有 API 密钥进行认证，并请求包含预签名链接的响应；每个链接都限定在单个资源上，携带签名和过期时间，查看者可直接使用返回的 URL，无需 API 密钥。

请将预签名 URL/令牌视为临时的持有者凭据：任何获得它的人都可以在过期前访问其签名的资源。签名覆盖 GET 方法、资源路径、tenantId 和 expires；keyId 选择验证密钥，而 signature 携带 HMAC。不要更改路径或这些认证参数。

文档中记录的未签名播放器选项（如 controls、autoplay、mode、speed 和 time）以及截图选项（如 time、width、height 和 quality）可以追加或更改，而不会使链接失效。这些选项不受完整性保护，因此当它们对你的应用至关重要时，请单独验证或约束它们。