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.

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.

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

How authentication works Credential resolution order and the transport header each mode sends.

Configure Auth Token mode Switch to Auth Token mode and configure the token endpoint in Project Settings.

Write a custom token provider Implement IConvaiAuthTokenProvider to fetch a token from your own login flow.

Connect with an existing auth token Use ConnectWithAuthTokenAsync when your login layer already holds a token.

Authentication scripting reference Full interface, registry, and settings surface for authentication.

Ship a secure build What the build processor strips and the WebGL CORS requirements for a token endpoint.

Troubleshoot authentication Console messages and error codes for both authentication modes.

Next steps

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

Configure the API key

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

How authentication works