> 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/connect-with-auth-token.md).

# Connect with an existing auth token

Pass an already-issued Convai auth token directly into a single connection call when your login layer already holds one.

Call `ConnectWithAuthTokenAsync` when your project already resolves a Convai auth token somewhere else — for example, in a login flow that requests one before the player enters the scene — and you want to hand that token to a single connection attempt instead of registering a provider.

### Prerequisites

* The project's `ConvaiSettings` asset has `AuthMode` set to `AuthToken`. See [Configure Auth Token mode](/api-docs/plugins-and-integrations/convai-unity-sdk/authentication/configure-auth-token-mode.md).
* A valid, unexpired Convai auth token (an `apiAuthToken`) obtained from your own backend.
* A stable, non-secret end-user ID and a display name for the connecting player.

{% hint style="info" %}
If a scene component or a login-triggered flow can resolve the token itself, register an [`IConvaiAuthTokenProvider`](/api-docs/plugins-and-integrations/convai-unity-sdk/authentication/custom-token-provider.md) instead. Use `ConnectWithAuthTokenAsync` when the token already exists in code that calls the connection directly — for example, immediately after a sign-in call returns it.
{% endhint %}

### Call ConnectWithAuthTokenAsync

`ConvaiManager.ActiveManager.ConnectWithAuthTokenAsync` takes the token plus the end-user identity for this connection:

```csharp
using System.Threading;
using System.Threading.Tasks;
using Convai.Runtime.Components;
using Convai.Runtime.Core.Async;
using UnityEngine;

public async Task ConnectSignedInPlayerAsync(
    string convaiAuthToken,
    string playerAccountId,
    string playerDisplayName,
    CancellationToken cancellationToken)
{
    try
    {
        var session = await ConvaiManager.ActiveManager.ConnectWithAuthTokenAsync(
            convaiAuthToken,
            playerAccountId,
            playerDisplayName,
            cancellationToken);
    }
    catch (ConvaiOperationException exception)
    {
        Debug.LogError($"Auth-token connection failed: {exception.Message}");
    }
}
```

All three string parameters are required. Passing an empty or whitespace-only `authToken`, `endUserId`, or `endUserName` throws a `ConvaiOperationException` before any network call is made.

| Parameter           | Maps to                                     | Description                                                    |
| ------------------- | ------------------------------------------- | -------------------------------------------------------------- |
| `authToken`         | Request credential for this connection only | The short-lived Convai auth token to use.                      |
| `endUserId`         | `end_user_id`                               | A stable, non-secret identifier for the connecting player.     |
| `endUserName`       | `end_user_metadata.name`                    | The player's display name.                                     |
| `cancellationToken` | —                                           | Cancels the pending connection attempt. Defaults to `default`. |

{% hint style="warning" %}
`ConnectWithAuthTokenAsync` uses the supplied token for that one connection attempt only. The SDK does not cache it, so a later plain `ConnectAsync()` call does not reuse it — resolve a fresh token before every connection made this way.
{% endhint %}

### Why the project must still be in Auth Token mode

Passing a token to `ConnectWithAuthTokenAsync` does not switch the project's authentication mode. If `AuthMode` is still `ApiKey`, the connection fails with error code `ConfigAuthTokenModeRequired` and message:

```
Explicit auth-token connections require Auth Token mode in Convai Project Settings.
```

Set `AuthMode` to `AuthToken` in **Edit > Project Settings > Convai SDK > Credentials** before using this method, even if no endpoint URL or registered provider is configured there.

### Verify the connection

Call `ConnectWithAuthTokenAsync` with a valid token and confirm the returned `RoomSession` resolves without an exception. If the token is invalid or expired, the call throws a `ConvaiOperationException` with error code `ConnectionInvalidToken` and message `Connection token is invalid`.

### Next steps

{% content-ref url="/pages/RLgjBrRsdfQZ9yCWavdD" %}
[Write a custom token provider](/api-docs/plugins-and-integrations/convai-unity-sdk/authentication/custom-token-provider.md)
{% endcontent-ref %}

{% content-ref url="/pages/hU1HhBYKZDoChhsoNKJN" %}
[Authentication scripting reference](/api-docs/plugins-and-integrations/convai-unity-sdk/authentication/scripting-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/KS7LOFRhjJV0jNeUBAo9" %}
[Troubleshoot authentication](/api-docs/plugins-and-integrations/convai-unity-sdk/authentication/troubleshooting.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/connect-with-auth-token.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.