> 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.md).

# Authentication

Compare Convai Unity SDK API Key and Auth Token authentication modes, understand when each applies, and see what ships in a player build.

Every connection from a Unity project to Convai needs a credential that proves the project is allowed to talk to Convai. The Convai SDK for Unity supports two ways to supply that credential: a saved account API key, or a short-lived token minted by a server you control. This section explains both modes and shows how to configure, extend, and troubleshoot each one.

### The two authentication modes

`ConvaiAuthMode` (`ApiKey = 0`, `AuthToken = 1`) controls how a `ConvaiManager` resolves credentials for every room connection.

| Mode           | How the credential is obtained                                                                                              | Where the credential lives                                                        |
| -------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| **API Key**    | The SDK reads the account API key saved in Convai Project Settings.                                                         | Stored on disk in the `ConvaiSettings` asset, obfuscated but not encrypted.       |
| **Auth Token** | The SDK resolves a short-lived token from a registered `IConvaiAuthTokenProvider`, or from an HTTPS endpoint you configure. | Held in memory for a single connection attempt; never written to disk by the SDK. |

### When each mode is appropriate

Use **API Key** mode for local development: iterating on a scene in the Unity Editor, running sample scenes, or testing on a machine only you control. It requires no server of your own.

Use **Auth Token** mode for anything you ship: a build distributed to testers, players, or end users. A player build in Auth Token mode never contains the account API key — a build processor strips it during the build and restores it afterward. A player build in API Key mode contains the account key, obfuscated with a reversible cipher, inside the shipped `ConvaiSettings` asset.

{% hint style="warning" %}
Obfuscation is not encryption. Anyone with the SDK source can reverse the stored API key. Do not ship an API Key mode build to an audience you do not fully trust.
{% endhint %}

### What ships in a player build

| Build produced with | API key present in the build                          | Credential resolved at connect time               |
| ------------------- | ----------------------------------------------------- | ------------------------------------------------- |
| API Key mode        | Yes, obfuscated in the `ConvaiSettings` asset         | Read directly from the asset                      |
| Auth Token mode     | No — stripped before the build and restored afterward | Fetched from your registered provider or endpoint |

### Choose a page

<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>How authentication works</strong><br>Credential resolution order and the transport header each mode sends.</td><td><a href="/api-docs/plugins-and-integrations/convai-unity-sdk/authentication/how-authentication-works.md">How authentication works</a></td></tr><tr><td><strong>Configure Auth Token mode</strong><br>Switch to Auth Token mode and configure the token 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>Implement IConvaiAuthTokenProvider to fetch a token from your own login flow.</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 ConnectWithAuthTokenAsync when your login layer already holds a token.</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><tr><td><strong>Authentication scripting reference</strong><br>Full interface, registry, and settings surface for authentication.</td><td><a href="/api-docs/plugins-and-integrations/convai-unity-sdk/authentication/scripting-reference.md">Authentication scripting reference</a></td></tr><tr><td><strong>Ship a secure build</strong><br>What the build processor strips and the WebGL CORS requirements for a token endpoint.</td><td><a href="/api-docs/plugins-and-integrations/convai-unity-sdk/authentication/ship-a-secure-build.md">Ship a secure build</a></td></tr><tr><td><strong>Troubleshoot authentication</strong><br>Console messages and error codes for both authentication modes.</td><td><a href="/api-docs/plugins-and-integrations/convai-unity-sdk/authentication/troubleshooting.md">Troubleshoot authentication</a></td></tr></tbody></table>

### Next steps

If you are configuring your first project, start with the API key.

{% content-ref url="/pages/nLYDmLXfx19u9jY8DiYD" %}
[Configure the API key](/api-docs/plugins-and-integrations/convai-unity-sdk/getting-started/configure-api-key.md)
{% endcontent-ref %}

When you are ready to ship a build, read how credential resolution works before configuring Auth Token mode.

{% content-ref url="/pages/C0S65jHID9u4IxrrZ6Iz" %}
[How authentication works](/api-docs/plugins-and-integrations/convai-unity-sdk/authentication/how-authentication-works.md)
{% endcontent-ref %}


---

# 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.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.