> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/how-authentication-works.md).

# 身份验证如何运作

了解 Convai Unity SDK 遵循的凭证解析顺序，以及每种身份验证模式发送的传输头。

Unity 版 Convai SDK 会在每次房间连接尝试时重新解析凭据——它不会在连接之间缓存令牌。了解解析顺序有助于你决定是注册提供程序、配置端点，还是显式传入令牌。

### 凭据解析顺序

在 Auth Token 模式下， `AuthTokenCredentialProvider.EnsureCredentialsAsync` 会在每次连接尝试时运行一次，并按以下顺序检查三个来源：

1. **显式的一次性令牌。** 如果当前连接是通过 `ConvaiManager.ConnectWithAuthTokenAsync`启动的，SDK 会使用该令牌，并跳过另外两个来源。
2. **已注册的 `IConvaiAuthTokenProvider`.** 如果没有提供显式令牌，SDK 会检查 `ConvaiAuthTokenProviderRegistry` 中是否有提供程序，并调用 `GetTokenAsync` 。
3. **在项目设置中配置的端点。** 如果没有注册提供程序，SDK 会回退到 `EndpointAuthTokenProvider`，它由以下内容构建： **令牌端点 URL**, **HTTP 方法**, **令牌响应字段**，以及 **请求标头** 保存在 **Edit > Project Settings > Convai SDK**.

如果这三个来源都没有产出令牌，连接将失败并报错 `Auth Token 模式需要已注册的 IConvaiAuthTokenProvider 或已配置的端点 URL。`

```mermaid
sequenceDiagram
    participant Manager as ConvaiManager
    participant Credential as AuthTokenCredentialProvider
    participant Provider as IConvaiAuthTokenProvider
    participant Endpoint as 已配置的端点
    participant Convai

    Manager->>Credential: EnsureCredentialsAsync
    alt 此连接已设置显式令牌
        Credential->>Credential: 消费显式令牌
    else 已注册提供程序
        Credential->>Provider: GetTokenAsync
        Provider-->>Credential: AuthTokenResult
    else 未注册提供程序
        Credential->>Endpoint: 请求令牌
        Endpoint-->>Credential: apiAuthToken
    end
    Credential-->>Manager: 已解析的令牌
    Manager->>Convai: 使用 API-AUTH-TOKEN 标头连接
```

在 API Key 模式下，解析更简单： `ProjectSettingsCredentialProvider` 直接从已保存的 `ConvaiSettings` 资源文件中读取账户 API 密钥。这里不涉及提供程序、端点或每次连接的网络调用。

### 哪种来源适用于你的集成

| 你的情况                                | 适用来源                                  |
| ----------------------------------- | ------------------------------------- |
| 在连接之前，你的登录层已经持有一个 Convai auth token | 通过显式一次性令牌 `ConnectWithAuthTokenAsync` |
| 你希望将每个玩家的令牌与你自己的登录系统绑定              | 已注册的 `IConvaiAuthTokenProvider`       |
| 你的令牌端点接受未经身份验证的请求，或者你正在做原型开发        | 在项目设置中配置的端点                           |

当同一次连接尝试同时存在显式令牌和已注册提供程序时，显式令牌始终优先——在这种情况下不会去调用提供程序。

### 每种模式对应的传输标头

SDK 发送给 Convai 的标头会因身份验证模式而异，而不是因平台而异：

| 模式     | 标头名称             |
| ------ | ---------------- |
| API 密钥 | `X-API-Key`      |
| 身份验证令牌 | `API-AUTH-TOKEN` |

`TransportAuthenticationSupport.GetHeaderName` 从活动的 `ITransportConfiguration`中选择标头。Native 和 WebGL 房间控制器调用的是同一套选择逻辑，因此两个平台上的标头名称和身份验证模式处理都是一致的——无需考虑 WebGL 特有的标头变体。

### 仅编辑器回退

当选择 Auth Token 模式、已保存 API 密钥且未配置端点或提供程序时，编辑器会直接向 Convai 交换已保存的 API 密钥以获取令牌。此回退仅存在于 `ConvaiEditorApiKeyAuthTokenProvider`中，这是一个编辑器程序集类型，从不会编译进玩家构建——在 Auth Token 模式下，发布构建始终依赖真实的提供程序或端点，而绝不会使用此回退。

### 下一步

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>配置 Auth Token 模式</strong><br>切换模式并在项目设置中配置端点。</td><td><a href="/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/configure-auth-token-mode.md">配置 Auth Token 模式</a></td></tr><tr><td><strong>编写自定义令牌提供程序</strong><br>注册 IConvaiAuthTokenProvider 以提供每个玩家的令牌。</td><td><a href="/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/custom-token-provider.md">编写自定义令牌提供程序</a></td></tr><tr><td><strong>使用现有身份验证令牌进行连接</strong><br>使用一次性的 ConnectWithAuthTokenAsync 路径。</td><td><a href="/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/connect-with-auth-token.md">使用现有身份验证令牌连接</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication/how-authentication-works.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.