Skip to content

Migrating from the old Vendor API

Jump to bottom
Chloe41427 edited this page Sep 27, 2026 · 1 revision

Migrating from the old Vendor API

If you previously published to SDKMAN! using the old vendors.sdkman.io API with Consumer-Key / Consumer-Token headers, this page maps the old world onto the new one. The old API is superseded by the SDKMAN! State API at https://state.sdkman.io.

If you're onboarding fresh, you don't need this page - start with the Vendor Onboarding guide instead.

What changed, at a glance

Old Vendor API New State API
Base URL https://vendors.sdkman.io https://state.sdkman.io
Auth Consumer-Key + Consumer-Token headers on every call POST /login → short-lived JWT bearer token (10 min)
Publish a version POST /release POST /versions
Remove a version DELETE /release DELETE /versions
Set default PUT /default Assign the lts tag (no dedicated call)
Announce POST /announce/struct (X/Twitter + broadcast) Removed - see below
Multi-vendor Java $version-$vendor string (11.0.10-zulu) Separate distribution field
Platform names LINUX_64, MAC_OSX, … LINUX_X64, MAC_X64, …

Authentication

Before: you sent static credentials as headers on every request:

-H "Consumer-Key: CONSUMER_KEY" -H "Consumer-Token: CONSUMER_TOKEN"

Now: you exchange an email + password for a short-lived JWT, then send it as a bearer token:

TOKEN=$(curl -sf -X POST https://state.sdkman.io/login \
  -H "Content-Type: application/json" \
  -d '{"email":"vendor@example.com","password":"your-password"}' \
  | jq -r '.token')

curl -sf -X POST https://state.sdkman.io/versions \
  -H "Authorization: Bearer $TOKEN" ...

Tokens last 10 minutes and there are no refresh tokens - just log in again. Login is rate-limited (5 attempts/min per IP, returning 429).

Your existing Consumer-Key/Consumer-Token credentials no longer work. You'll be issued a vendor email + password during onboarding.

Publishing a version

Before:

curl -X POST \
  -H "Consumer-Key: ..." -H "Consumer-Token: ..." \
  -d '{"candidate":"groovy","version":"2.4.2","url":"https://.../groovy.zip"}' \
  https://vendors.sdkman.io/release

Now:

curl -sf -X POST https://state.sdkman.io/versions \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"candidate":"groovy","version":"2.4.2","platform":"UNIVERSAL",
       "url":"https://.../groovy.zip"}'

Note: platform is now required - use UNIVERSAL if your SDK ships a single archive (it's no longer implicit). Success is 204 No Content.

Setting the default

The old PUT /default call is gone. The default is now derived from the lts tag - assign it to the version you want as default:

curl -sf -X POST https://state.sdkman.io/versions/tags \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"candidate":"groovy","version":"2.4.2","platform":"UNIVERSAL","tag":"lts"}'

See Tags, latest & the Default Version for the full model.

Platform name changes

The platform identifiers were renamed. If your pipeline hard-codes the old ones, update them:

Old New
LINUX_64 LINUX_X64
LINUX_ARM64 LINUX_ARM64 (unchanged)
LINUX_32 LINUX_X32
LINUX_ARM32HF LINUX_ARM32HF (unchanged)
LINUX_ARM32SF LINUX_ARM32SF (unchanged)
MAC_OSX MAC_X64
MAC_ARM64 MAC_ARM64 (unchanged)
WINDOWS_64 WINDOWS_X64

See the Platform & Distribution Reference for the complete list.

Multi-vendor Java to distributions

The old API encoded the JDK vendor into the version string as $version-$vendor (e.g. 11.0.10-zulu). That's replaced by a first-class distribution field (ZULU, TEMURIN, CORRETTO, …), keeping version and distribution as separate concepts.

In practice this rarely affects you: Java is now published automatically via the Foojay DISCO API, not by vendors through the API.

Announcements are gone

The old POST /announce/struct endpoint (which posted to the SDKMAN! CLI broadcast and the X/Twitter feed) has been removed. Release announcements are no longer part of the publishing API. The X/Twitter account has been retired; SDKMAN! now announces on Mastodon and Bluesky through its own release pipeline.

The old plugins and GitHub Action

  • The Gradle and Maven vendor plugins targeted the old API and are effectively retired. Don't build new integrations on them.
  • The sdkman-release-action currently still uses the old auth; it's being retrofitted to handle JWT transparently. Until that lands, use the curl-based flow in the Integration Guide.

Stuck mid-migration? Ask in the #vendors channel on Discord - happy to help.

Clone this wiki locally