> 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/plugins-and-integrations/convai-unity-sdk/authentication/how-authentication-works.md).

# How authentication works

Understand the credential resolution order the Convai Unity SDK follows and the transport header each authentication mode sends.

The Convai SDK for Unity resolves a credential fresh for every room connection attempt — it does not cache a token across connections. Understanding the resolution order helps you decide whether to register a provider, configure an endpoint, or pass a token explicitly.

### Credential resolution order

In Auth Token mode, `AuthTokenCredentialProvider.EnsureCredentialsAsync` runs once per connection attempt and checks three sources, in order:

1. **An explicit one-shot token.** If the current connection was started with `ConvaiManager.ConnectWithAuthTokenAsync`, the SDK consumes that token and skips the other two sources.
2. **A registered `IConvaiAuthTokenProvider`.** If no explicit token was supplied, the SDK checks `ConvaiAuthTokenProviderRegistry` for a provider and calls `GetTokenAsync` on it.
3. **The endpoint configured in Project Settings.** If no provider is registered, the SDK falls back to `EndpointAuthTokenProvider`, built from the **Token Endpoint URL**, **HTTP Method**, **Token Response Field**, and **Request Headers** saved under **Edit > Project Settings > Convai SDK**.

If none of the three sources yields a token, the connection fails with the error `Auth Token mode requires a registered IConvaiAuthTokenProvider or a configured endpoint URL.`

```mermaid
sequenceDiagram
    participant Manager as ConvaiManager
    participant Credential as AuthTokenCredentialProvider
    participant Provider as IConvaiAuthTokenProvider
    participant Endpoint as Configured endpoint
    participant Convai

    Manager->>Credential: EnsureCredentialsAsync
    alt Explicit token set for this connection
        Credential->>Credential: Consume explicit token
    else Provider registered
        Credential->>Provider: GetTokenAsync
        Provider-->>Credential: AuthTokenResult
    else No provider registered
        Credential->>Endpoint: Request token
        Endpoint-->>Credential: apiAuthToken
    end
    Credential-->>Manager: Resolved token
    Manager->>Convai: Connect with API-AUTH-TOKEN header
```

In API Key mode, resolution is simpler: `ProjectSettingsCredentialProvider` reads the account API key directly from the saved `ConvaiSettings` asset. No provider, endpoint, or per-connection network call is involved.

### Which source applies to your integration

| Your situation                                                               | Applicable source                                       |
| ---------------------------------------------------------------------------- | ------------------------------------------------------- |
| Your login layer already holds a Convai auth token before connecting         | Explicit one-shot token via `ConnectWithAuthTokenAsync` |
| You want per-player tokens tied to your own login system                     | A registered `IConvaiAuthTokenProvider`                 |
| Your token endpoint accepts unauthenticated requests, or you are prototyping | The endpoint configured in Project Settings             |

An explicit token always wins when both an explicit token and a registered provider are present for the same connection attempt — the provider is not consulted in that case.

### Transport header per mode

The header the SDK sends to Convai differs by authentication mode, not by platform:

| Mode       | Header name      |
| ---------- | ---------------- |
| API Key    | `X-API-Key`      |
| Auth Token | `API-AUTH-TOKEN` |

`TransportAuthenticationSupport.GetHeaderName` selects the header from the active `ITransportConfiguration`. The Native and WebGL room controllers call the same selection logic, so the header name and the authentication-mode handling are identical on both platforms — there is no WebGL-specific header variant to account for.

### Editor-only fallback

When Auth Token mode is selected, an API key is saved, and no endpoint or provider is configured, the Editor exchanges the saved API key for a token directly against Convai. This fallback exists only inside `ConvaiEditorApiKeyAuthTokenProvider`, an Editor-assembly type that is never compiled into a player build — a shipped build in Auth Token mode always relies on a real provider or endpoint, never on this fallback.

### Next steps

<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>Configure Auth Token mode</strong><br>Switch modes and configure the endpoint in Project Settings.</td><td><a href="/api-docs/plugins-and-integrations/convai-unity-sdk/authentication/configure-auth-token-mode.md">Configure Auth Token mode</a></td></tr><tr><td><strong>Write a custom token provider</strong><br>Register an IConvaiAuthTokenProvider for per-player tokens.</td><td><a href="/api-docs/plugins-and-integrations/convai-unity-sdk/authentication/custom-token-provider.md">Write a custom token provider</a></td></tr><tr><td><strong>Connect with an existing auth token</strong><br>Use the one-shot ConnectWithAuthTokenAsync path.</td><td><a href="/api-docs/plugins-and-integrations/convai-unity-sdk/authentication/connect-with-auth-token.md">Connect with an existing auth token</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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/plugins-and-integrations/convai-unity-sdk/authentication/how-authentication-works.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.