How do I migrate my Unity Build Automation (UBA) REST API calls from V1 to V2?

Relevant context or prerequisites:

• The Build Automation V1 API will be deprecated and removed on December 21, 2026. After this date, V1 endpoints will return HTTP 410 Gone (or 404 Not Found) and any calls to them will stop working. Migrate to the V2 API before this date to avoid disruption.
• You need access to the Unity Cloud Dashboard (cloud.unity.com) with permissions to create Service Accounts and manage roles at the organization or project level.
• V2 uses HTTP Basic Authentication with a Service Account Key ID and Secret Key. No token-exchange step is required (see the authentication note below).
• Have your Organization ID and Project ID ready, both available in the Unity Cloud Dashboard.

Key differences between V1 and V2:

Detailed procedure:

Step 1 — Create a Service Account

1. Go to the Unity Cloud Dashboard (cloud.unity.com) and navigate to Administration.
2. Select Service Accounts and click Create service account.
3. Give it a descriptive name (e.g. "Build Automation CI") and save.

Step 2 — Create an API key

1. Open the Service Account you just created.
2. Under Keys, click Create key.
3. Unity will display the new credentials one time only:
   • Key ID
   • Secret key
   • Authorization header (a pre-encoded Basic <base64> value)
4. Copy and store those securely — the Secret key cannot be retrieved again after you close the dialog.

Step 3 — Assign a role

1. In the Service Account, click Manage roles (organization level) or Manage project roles (project level).
2. Expand the Automation category, select the Automation User role, and save.

You can grant the role at the organization level (applies to all projects) or at the project level (applies to a single project). Without a role assigned, the API will return HTTP 403 Forbidden.

Step 4 — Update your API calls

For V2, authenticate using Basic auth by passing the Key ID and Secret key with curl's -u flag. Below are equivalent examples in both API versions.

Example — List build targets (GET):

V1:

curl -s -X GET "https://build-api.cloud.unity3d.com/api/v1/orgs/{ORG_ID}/buildtargets" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {V1_API_KEY}"

V2:

curl -s -X GET "https://build-automation.services.api.unity.com/v2/orgs/{ORG_ID}/projects/{PROJECT_ID}/buildtargets" \
  -u "{KEY_ID}:{SECRET_KEY}" \
  -H "Accept: application/json"

Example — Trigger a build (POST):

V1:

curl -s -X POST "https://build-api.cloud.unity3d.com/api/v1/orgs/{ORG_ID}/projects/{PROJECT_ID}/buildtargets/{BUILD_TARGET_ID}/builds" \
  -H "Authorization: Bearer {V1_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"clean": false}'

V2:

curl -s -X POST "https://build-automation.services.api.unity.com/v2/orgs/{ORG_ID}/projects/{PROJECT_ID}/buildtargets/{BUILD_TARGET_ID}/builds" \
  -u "{KEY_ID}:{SECRET_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"clean": false}'

A successful build request returns HTTP 202 Accepted. An empty body ({"clean": false}) uses the branch, platform, and machine configuration already defined on the build target; you only need to include additional fields to override those defaults.

Notes on authentication:

• As an alternative to -u, you can use the pre-generated Authorization header from Step 2: -H "Authorization: Basic {BASE64_HEADER}". Both are equivalent — Basic auth is simply the base64 encoding of KEY_ID:SECRET_KEY.
• Do not use the Unity Services token-exchange endpoint (services.api.unity.com/auth/v1/token-exchange) for V2 Build Automation; the resulting Bearer token is not accepted by this API and will return 401 Untrusted issuer.

Additional Information:

• V1 API reference: https://build-api.cloud.unity3d.com/docs/
• V2 API reference: https://docs.unity.com/en-us/oas-build-automation-client/2.0.0
• Creating a Service Account