Skip to main content

[Billing] Resolving Authentication Issues in Unity Version Control CI/CD Integrations

Updated

This article explains how CI/CD setups that use the UVCS plugin can experience errors and timeouts due to expiring Unity ID tokens or account mismatches. The recommended fix is using Personal Access Tokens, which provide more stable authentication. Step-by-step instructions for generating and configuring these tokens are included to ensure smoother automated builds and downloads.

Symptoms

  • I am using a CI/CD tool, such as TeamCity with its UVCS plugin, to build projects, but I get timeouts or errors, such as "Error: The handle is invalid".

Causes

When performing large downloads or long-running operations, the standard Unity ID (OIDC) authentication token may expire before the process completes.

There can also be configuration mismatches between your user account and the system account running your CI/CD service.

Solution

Using Personal Access Tokens instead of UnityID (the default authorization gateway) is a workaround for the issues above.

Here are the steps to implement them:

1. As an administrator, create a Personal Access Token in the target Cloud organization:

$ cm accesstoken create "Token for CICD" 90d <your_org>@unity

The result should be:

          Id  2023d611-fa69-46c5-b8b4-4e405c780bb7
 Description  My Script PAT
       Owner  you@your-org.com
  Created at  8/4/2025 4:10:57PM
  Expires at  9/3/2025 4:10:57PM
Last used at  Never

If you get a message saying you don't have permission to create the access token, please make sure the user is in the allowlist using this command:

$ cm accesstoken admin allowlist show my-org@unity

Then, grant access to the feature by ensuring you add the user to the allowlist:

$ cm accesstoken admin allowlist add --users=your-user@email.com my-org@unity

2. Reveal the corresponding Personal Access Token:

$ cm accesstoken reveal 74f20cad-eca3-44a3-a963-5450fba7adba my-org@unity

The result should look like this:

eyJhbGciOiJkpXVCJ9.eyJzdWIiOiIAyMn0.KMUFsI-QV30

3. Take that token and replace it in your %LOCALAPPDATA%\plastic4\tokens.conf file (or ~/.plastic4/tokens.conf):

server=1234567890@unity user=your-user@email.com token=<REPLACE HERE> seiddata=your-user@email.com

4. Retry the operation (pull, build).

More Information

To learn more about Personal Access Tokens management from the command line for Unity Cloud organizations, please review this release notes entry.

Related articles