Migrating from API v1 to API v2

Draft status: This page has several items marked CONFIRM WITH ENGINEERING. Do not publish externally until those are resolved.

Chainguard’s API v2 is now Generally Available (GA) across every product domain: Customer Platform (IAM), Containers, Ecosystems, and Integrations. At GA, the “beta” designation is dropped: endpoints move from /v2beta1/ to /v2/. This guide covers what changed from v1, and the steps to migrate an existing direct integration.

If you only use chainctl, the Chainguard Console, or the Terraform provider, you don’t need this guide — those clients handle versioning for you, and nothing changes on your end. This guide is for anyone calling the API directly: curl, gRPC, or a custom SDK integration.

v1 continues to work during a transition period, so nothing breaks today. Migrate at your own pace; see Timeline for what happens next.

Prerequisites

You’ll need:

• A valid Chainguard identity with access to the resources you’re calling.
• chainctl installed, to mint a token for testing (chainctl auth token).

Set up your environment for the following examples:

export TOKEN=$(chainctl auth token)
export API=https://console-api.enforce.dev
# ORG_ID is the UID of your root organization group
export ORG_ID=YOUR_ORG_ID

What’s not changing

• Authentication — same OIDC token model as v1.
• Authorization — same identity-based access control.
• Scoping — same uidp.descendants_of / uidp.children_of hierarchy filters.
• Host — same API host (console-api.enforce.dev in production).

If your integration already authenticates against v1 successfully, no credential or auth-flow changes are needed to call v2.

Quick reference

Path prefixes by domain

If you built against the beta endpoints, updating the version segment from v2beta1 to v2 is the only path change — the request and response shapes don’t change as part of that rename.

Migration steps

Step 1: Update your endpoint paths

Add the v2 version segment for each domain you call, using the path prefix table. If you were already on /v2beta1/, rename it to /v2/.

Step 2: Update field references

v2 standardizes field naming across every service:

• Resource identifiers are always uid, never id.
• Timestamps are createTime / updateTime, not created_at / updated_at.
• All fields use camelCase.

Update any code that reads specific field names out of API responses — these differ from v1 even for the same resource.

Step 3: Move CREATE calls to parent-in-body

v1 identifies the parent resource in the URL path (for example, /groups/{parent}). v2 moves the parent identifier into the request body instead, alongside the fields of the resource being created.

v1 (illustrative):

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "$API/iam/groups/$PARENT_UID" \
  -d '{"name": "my-group"}'

v2 (illustrative):

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "$API/iam/v2/groups" \
  -d '{"parent": "'"$PARENT_UID"'", "group": {"name": "my-group"}}'

CONFIRM WITH ENGINEERING: this request body is illustrative. Get the exact body schema — including the "group" wrapper field name — from engineering before publishing.

Stop building create-call URLs with the parent embedded in the path. Build a request body that includes both the parent identifier and the new resource’s fields instead.

Step 4: Switch updates to PATCH with a field mask

v1 uses PUT semantics: changing one field means sending the entire resource back, which forces a fetch-before-write pattern and creates race conditions on concurrent updates. v2 uses PATCH with a field mask, so you specify only the fields you’re changing.

curl -X PATCH -H "Authorization: Bearer $TOKEN" \
  "$API/iam/v2/groups/$GROUP_UID?updateMask=description" \
  -d '{"description": "updated description"}'

Testing against the live beta API confirmed this updateMask parameter name works. It’s presumed unchanged at GA, but worth a final confirmation since none of the GA source docs restate it.

Replace fetch-modify-write update logic with a PATCH call that sets only the fields you’re changing. A wildcard * is available if you genuinely want full replacement.

Repository updates (UpdateRepo) are a common case to migrate here. For a worked repo PATCH example, see Partial updates with FieldMask in the tutorial.

Step 5: Switch pagination to cursor-based

v1 pagination relies on page numbers or offsets, and loads the full result set into memory. v2 List endpoints add:

• page_size — how many items to return per page.
• page_token — the opaque cursor from the previous response’s next_page_token, used to fetch the next page. Omit it for the first page.
• skip — number of items to skip, for jumping directly to a specific page without walking the cursor sequentially.
• order_by — server-side ordering, instead of sorting client-side after fetching.
• total_count — total matching items, so you don’t have to infer it from page math.

curl -H "Authorization: Bearer $TOKEN" \
  "$API/iam/v2/groups?uidp.descendants_of=$ORG_ID&page_size=3&order_by=name" | jq .

Replace any page-number or offset logic with a loop that follows page_token until the response stops returning one. Use skip instead if you need to jump to an arbitrary page. Adopt order_by and drop any client-side sort you were doing to compensate.

Step 6: Use dedicated Get endpoints

v1 typically requires filtering a List call to fetch a single resource. v2 adds a dedicated Get endpoint per resource, fetched by uid directly.

curl -H "Authorization: Bearer $TOKEN" \
  "$API/iam/v2/groups/$GROUP_UID"

Replace any “list and filter to one item” pattern with the dedicated Get endpoint for that resource.

Step 7: Update your error handling

In v1, an empty or ambiguous result can mean several different things — no matches, no permission, or a missing parent resource — with no way for a client to tell them apart. For example, requesting a resource that doesn’t exist in v1 returns an empty result with HTTP 200.

v2 returns proper status codes (for example, NOT_FOUND / HTTP 404) with structured error details, following the same error model used across Google Cloud APIs:

• ErrorInfo — a machine-readable reason code and error domain.
• BadRequest — per-field validation errors.
• ResourceInfo — which specific resource type and name wasn’t found.
• PreconditionFailure — why a request was blocked (for example, a delete blocked by a dependent resource).

If your integration currently treats an empty v1 result as ambiguous, or works around that ambiguity with extra calls, update it to branch on the v2 status code and structured error details instead. Re-test your error-handling paths, not just the happy path.

Step 8: Review rate limits

Rate limits were not enforced during beta. They are enforced starting at GA.

CONFIRM WITH ENGINEERING: specific rate limits and response headers (for example, remaining-quota headers). Add them here once confirmed, and link out to a rate-limits reference page if one exists.

Review your call patterns — polling frequency, batch sizes — against the confirmed limits before cutting production traffic over.

Step 9: Update gRPC and SDK clients

All v2 endpoints are also available directly via gRPC, at the same host. Proto definitions are at chainguard.dev/sdk/proto/chainguard/platform/. If you call the API via generated gRPC clients, regenerate them against the GA v2 proto packages, renamed from v2beta1.

CONFIRM WITH ENGINEERING: whether the Go SDK client library actually moves from chainguard.dev/sdk/proto/platform/clients/v2beta1 to an equivalent v2 path at GA, or keeps the v2beta1 package name internally even after the REST paths rename.

Full example: listing and deleting groups

Before (v1):

curl -H "Authorization: Bearer $TOKEN" \
  "$API/iam/groups?uidp.descendants_of=$ORG_ID"

After (v2):

curl -H "Authorization: Bearer $TOKEN" \
  "$API/iam/v2/groups?uidp.descendants_of=$ORG_ID&page_size=3&order_by=name" | jq .

Delete calls follow the same path-prefix change, with no other behavior change:

curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "$API/iam/v2/roleBindings/$BINDING_UID"
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "$API/iam/v2/identities/$IDENTITY_UID"
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "$API/iam/v2/groups/$GROUP_UID"

Each DELETE returns an empty response body on success, same as v1. A delete blocked by a dependent resource now returns a PreconditionFailure error detail explaining why, instead of an ambiguous failure.

Timeline

CONFIRM WITH ENGINEERING: every date in this timeline is a placeholder. Don’t ship this table as-is.

Don’t wait for a hard deadline to start testing v2 — both versions are available today, and migration can happen incrementally.

Troubleshooting

Will my existing integration stop working today? No. v1 keeps working during the parallel availability period. Nothing changes for existing integrations until the sunset date, which will be communicated well in advance.

Do I need new credentials for v2? No. Authentication and authorization are unchanged — the same tokens and identities that work with v1 work with v2.

Why did an API call that used to return an empty list now return an error? This is expected, and it’s an improvement. In v1, a missing resource and an empty result look the same, so there was no way to tell “nothing matched” apart from “that resource doesn’t exist” or “you don’t have permission.” v2 returns a specific, structured error in those cases instead.

Why did my create call stop working? Check whether you’re building the request URL with the parent resource in the path — that’s the v1 pattern. In v2, the parent goes in the request body instead. See Step 3.

Where do I send a customer who asks about migrating? This guide. If you’re on the account or support team, reach out to Engineering for anything marked CONFIRM WITH ENGINEERING in this guide rather than guessing at specifics.

Next steps

• Chainguard API v2 Tutorial — worked examples of the v2 endpoints you’ll be migrating to.
• Chainguard API v2 Specification — full OpenAPI reference.
• Reach out to your Chainguard account team or Chainguard Support if you run into issues migrating.