> 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/configure-auth-token-mode.md).

# Configure Auth Token mode

Switch a Convai Unity SDK project to Auth Token mode and configure the token endpoint in Project Settings for a shipped build.

Configure Auth Token mode so a player build resolves a short-lived credential from your backend instead of shipping the Convai account API key. Use this page when you have a token endpoint ready, or when you are configuring a public token endpoint directly in Project Settings.

### Prerequisites

* A Convai Unity SDK project with an API key already saved, so the Editor can keep working while you configure Auth Token mode.
* An HTTPS endpoint on your backend that returns a short-lived Convai auth token, unless you plan to use a code-based `IConvaiAuthTokenProvider` instead.

{% hint style="info" %}
If your integration uses a custom `IConvaiAuthTokenProvider` instead of a Project Settings endpoint, still complete steps 1–2 below to select **Auth Token** as the mode, then skip the endpoint fields. See [Write a custom token provider](/api-docs/plugins-and-integrations/convai-unity-sdk/authentication/custom-token-provider.md).
{% endhint %}

### Switch to Auth Token mode

{% stepper %}
{% step %}

#### Open the Credentials section

In the Unity Editor menu bar, open **Convai > Settings** (or **Edit > Project Settings > Convai SDK**), then select the **Credentials** section.
{% endstep %}

{% step %}

#### Set Auth Mode to Auth Token

Set **Auth Mode** to **Auth Token**. The Credentials section replaces the **API Key** group with the Auth Token configuration group.
{% endstep %}

{% step %}

#### Enter the Token Endpoint URL

Enter your backend's token endpoint in **Token Endpoint URL**. The endpoint must use HTTPS, except for an HTTP loopback URL used during local development — the SDK rejects any other non-HTTPS endpoint.
{% endstep %}

{% step %}

#### Select the HTTP method

Set **HTTP Method** to **GET** or **POST** to match how your endpoint expects the request.
{% endstep %}

{% step %}

#### Confirm the Token Response Field

Leave **Token Response Field** at its default, `apiAuthToken`, unless your endpoint returns the token under a different JSON field. This field supports dotted paths, so a nested field such as `data.token` resolves correctly.
{% endstep %}

{% step %}

#### Add request headers if your endpoint requires them

Add entries to **Request Headers** only for static values that are safe to include in a player build, such as an API version header. Leave this list empty if your endpoint needs no additional headers.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Project Settings headers are static and ship inside the player build. Never put a player token, refresh token, server secret, or Convai API key into the Request Headers list. If your token request needs a per-player credential, use a registered `IConvaiAuthTokenProvider` instead — see [Write a custom token provider](/api-docs/plugins-and-integrations/convai-unity-sdk/authentication/custom-token-provider.md).
{% endhint %}

### Verify the configuration

Enter Play mode with a scene that connects a `ConvaiCharacter`. A successful connection confirms the endpoint returned a valid token under the configured response field. If the connection fails, check the Console for the exact error message and see [Troubleshoot authentication](/api-docs/plugins-and-integrations/convai-unity-sdk/authentication/troubleshooting.md).

Your saved API key remains available to Editor tools after switching to Auth Token mode, but both stored key fields are cleared automatically while an Auth Token player build is produced, and restored afterward.

### 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>Write a custom token provider</strong><br>Register an IConvaiAuthTokenProvider for per-player tokens instead of a static endpoint.</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>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>


---

# 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/configure-auth-token-mode.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.