> ## Documentation Index
> Fetch the complete documentation index at: https://docs.renaiss.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 身份验证

> 保留应用自己的登录方式，使用开发者密钥授权请求，并为配送验证钱包。

你的应用负责登录和钱包连接。外部账户（EOA）无需登录 Renaiss 即可使用抽卡、市场和实物兑换。抽卡和市场 HTTP API 也接受符合条件的已部署合约钱包。每次操作都会分别检查开发者权限和钱包授权。

## 各项操作所需凭据

| 操作 | 开发者密钥 | 钱包访问令牌 | 钱包签名 |
| - | - | - | - |
| 公开市场目录、卡牌详情及订单簿 | 省略 | 无需 | 无需 |
| 卡包目录、内容及公开抽卡记录 | 可选 | 无需 | 无需 |
| 钱包收藏及链上活动 | 需要 | 无需 | 无需 |
| 抽卡准备、请求状态、钱包抽卡记录、结果及回购报价 | 需要 | 无需 | 无需 |
| 提交抽卡或回购 | 需要 | 无需 | 操作签名 |
| 准备市场交易 | 需要 | 无需 | 无需 |
| 市场下单、成交或撤单 | 需要 | 无需 | 操作签名 |
| 配送会话质询、验证、刷新或撤销 | 需要 | 无需 | 验证时签署消息 |
| 可兑换卡牌、报价、订单及物流 | 需要 | 需要 | 无需 |
| 提交兑换结账 | 需要 | 需要 | 操作签名 |

开发者密钥放在 `x-builder-api-key` 中。钱包令牌使用 `Authorization: Bearer <accessToken>`。接口同时要求两种凭据时，请同时发送两个请求头。钱包验证后才会签发访问令牌。请求质询时，`scopes` 必须同时包含 `redeem:read` 和 `redeem:write`。令牌仅授权该钱包与该开发者之间的私有兑换操作。

## 在后端保管密钥

让浏览器 SDK 调用你的后端，例如 `/api/renaiss`。后端转发到指定的 Renaiss API，仅对接受开发者密钥的路由添加密钥。公开市场查询请省略凭据。

后端应验证用户会话、逐项授权并限流。仅允许必要的上游路径和 HTTP 方法。由后端设置密钥，不要转发客户端传入的密钥。按需转发钱包访问令牌，并保留抽卡请求的流式响应。

不要将开发者密钥存入 `NEXT_PUBLIC_*` 变量或返回给浏览器。日常日志应排除访问令牌、刷新令牌、签名和收货信息。

## 选择执行操作的钱包

EOA 可直接为抽卡和市场操作签名。已部署的合约账户须通过 ERC-1271 验证操作签名，且验证逻辑必须将账户地址与签名意图绑定。买家或卖家地址应填合约账户本身。抽卡前还需确认它能接收 ERC-721 安全转账。

这些流程不支持 Renaiss 托管的 Safe 或 EIP-7702 委托账户。钱包会话和实物兑换仅支持 EOA。[TypeScript 测试版](https://docs.renaiss.xyz/cn/typescript-sdk.md#版本兼容性)使用 EOA 签名器。

## 验证配送钱包

在用户查看私有配送信息或开始兑换时发起验证。连接钱包后，用户还需签署允许访问配送数据的消息。之后提交结账时需要另签操作授权。

```ts theme={null}
import {
  BNB_TESTNET,
  createRedemptionClient,
  getError,
  isFailed,
  type RenaissSigner,
} from '@renaiss-protocol/client';

export async function verifyForShipping(signer: RenaissSigner) {
  const shipping = createRedemptionClient({
    baseUrl: '/api/renaiss',
    network: BNB_TESTNET,
    signer,
    walletSessionIssuer:
      'https://dev-api.renaiss.xyz/v2/auth/wallet',
  });

  const result = await shipping.signInRedemptionWallet({
    origin: window.location.origin,
  });
  if (isFailed(result)) throw new Error(getError(result).detail);
  return shipping;
}
```

后续私有请求应复用该客户端。它在内存中保存限定权限的凭据，并在会话有效期内刷新。用户退出、切换钱包或网络时，调用 `signOutRedemptionWallet()` 并清除界面中的私有数据。

### 前端来源与签发方

| 配置 | 示例 | 用途 |
| - | - | - |
| 已注册的前端来源 | `https://cards.example.com` | 发起签名的网页来源 |
| `walletSessionIssuer` | `https://dev-api.renaiss.xyz/v2/auth/wallet` | 签发并验证会话的 API |
| SDK 的 `baseUrl` | `/api/renaiss` | 浏览器发送请求的位置 |

注册完整的协议、主机和端口，不含路径或末尾斜杠。本地回环地址也要分别注册，例如 `http://localhost:3311` 和 `http://127.0.0.1:3311` 属于不同来源。

根据部署信息配置签发方。使用相对代理路径时必须显式指定；使用绝对 API URL 时，SDK 默认取其来源加上 `/v2/auth/wallet`。部署别名可能与规范签发方不同。不要从未经验证的签名质询中提取预期签发方。

### 会话有效期

| 项目 | 默认期限 | 到期后 |
| - | - | - |
| 签名质询 | 5 分钟 | 重新获取质询并签名 |
| 钱包访问令牌 | 15 分钟 | SDK 在会话有效期内刷新 |
| 可续期会话 | 7 天 | 重新验证钱包 |

签名提示过期或被取消后，钱包仍未验证。等用户再次选择验证时重试。此消息说明权限和会话期限，不授权链上交易。

直接使用 HTTP 时，可按以下顺序管理会话。

1. [获取登录消息](https://docs.renaiss.xyz/cn/api-reference/auth/get-sign-in-message.md)。提示用户签名前，先核对钱包、链、来源、签发方、受众、权限及有效期。SDK 会自动执行这些检查。
2. 请钱包逐字节签署原始消息，再[验证钱包签名](https://docs.renaiss.xyz/cn/api-reference/auth/verify-message.md)，获取访问令牌和刷新令牌。
3. 使用当前刷新令牌[续签会话](https://docs.renaiss.xyz/cn/api-reference/auth/refresh-tokens.md)。用户退出登录时，[撤销会话](https://docs.renaiss.xyz/cn/api-reference/auth/revoke-tokens.md)。

## 身份提供方

你可以使用 Privy 或其他嵌入式钱包的 EOA 签名器。其登录令牌不能用作 Renaiss 钱包访问令牌。此 API 不接受合作方的身份令牌或 JWKS 认证，请通过钱包验证获取令牌。

[使用 Renaiss 登录](https://docs.renaiss.xyz/cn/sso-integration.md)是可选的 OIDC 账户登录方式。钱包操作无需接入它，配送仍须单独验证。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.