SDK versioning policy

The canonical version of this policy lives in the compliance repo at authio_compliance/SDK-VERSIONING.md. This page mirrors it.

We follow Semantic Versioning 2.0.0

Every Authio SDK is versioned MAJOR.MINOR.PATCH per semver.org.

Pre-1.0 disclaimer (every SDK today)

Every Authio SDK is currently in the 0.x series. Per semver section 4: “Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.”

We are conservative even in 0.x — we minimise breaking changes between MINOR bumps and document every one in the changelog — but we reserve the right to make a non-additive change in a MINOR during 0.x. This is the same posture Stripe's beta libraries, OpenAI's SDKs, and Anthropic's SDKs take.

{
  "dependencies": {
    "@authio/node":  "0.1.0",
    "@authio/react": "~0.1.0"
  }
}

Post-1.0 SLA

When an SDK ships its 1.0.0 release we commit to:

• No breaking changes inside a MAJOR. Code that compiles against 1.0.0 compiles against every 1.x.y.
• Caret ranges are safe. ^1.0.0 in your package.json resolves only to non-breaking updates.
• Six-month deprecation window between announcing a deprecation and removing the surface in the next MAJOR. Every removal is preceded by a runtime warning, a @deprecated source annotation, a webhook event, and an email to project owners.
• No silent removals. Every method we plan to drop in the next MAJOR is listed as deprecated in the source and on this page.

Today every SDK is in 0.x; the first 1.0 candidate is @authio/node, on track for late 2026.

Per-SDK current state

State as of 2026-05-21. Confirm at the registry for the canonical version.

Upgrade procedure

1. Read the changelog. Every SDK has a CHANGELOG.md at the repo root. Cross-reference entries flagged BREAKING: against your codebase.
2. Update the dependency.

   # Node / Edge / React / Next.js / Vue
   pnpm add @authio/node@latest
   
   # Go
   go get github.com/tcast/authio_go@v0.2.0
   
   # Python
   uv pip install -U authio==0.2.0
   
   # iOS (CocoaPods)
   pod update Authio
   
   # Kotlin (Gradle)
   implementation("com.authio:authio-core:0.2.0")

3. Run typecheck + tests. pnpm typecheck && pnpm test on TS-shape; go vet ./... && go test ./... on Go; mypy && pytest on Python.
4. Deploy to staging and watch for regressions in audit_events rates (sign-in attempts, token refreshes).
5. Promote to production.

Breaking-change communication

Every breaking change in a MAJOR (post-1.0), and every breaking change in a MINOR (pre-1.0), is communicated through four channels:

1. Webhook event

{
  "type": "sdk.breaking_change.announced",
  "data": {
    "sdk": "@authio/node",
    "current_version": "1.4.0",
    "deprecated_in": "1.5.0",
    "removed_in": "2.0.0",
    "earliest_removal_date": "2026-11-21T00:00:00Z",
    "surface": "verifySession(token, opts)",
    "rationale": "Renamed opts.audience to opts.aud to match the JWT spec.",
    "migration_url": "https://docs.authio.com/reference/sdk-versioning#mig-node-2.0"
  }
}

Subscribe via webhooks to sdk.breaking_change.announced (or *) to surface these in your team's alerts.

2. Email to project owners

Sent from sdk-changes@authio.com to the owners of every project that has a recent (≤90 days) audit event tagged with the affected SDK's user agent. The email lists the migration steps and links to this page.

3. Changelog

Every breaking entry in CHANGELOG.md is prefixed with BREAKING: and lists the before/after diff inline.

4. Source-level deprecation

@deprecated JSDoc / Go doc / Python DeprecationWarning on the deprecated surface in the same release in which we announce. IDEs surface the warning on hover; the deprecated identifier is dimmed in completion lists.

Long-term support (LTS)

• Pre-1.0: no LTS. Track the latest MINOR.
• Post-1.0: every MAJOR receives PATCH backports (CVE / critical fixes only) for 12 months after the next MAJOR ships. So if 2.0.0 ships on 2027-01-01, 1.x stays patched until 2028-01-01.
• Custom LTS: available as part of an Enterprise contract. Pricing is part of the quote. Today no customer MSA names a specific LTS window.

Server / SDK compatibility

The Authio HTTP API is versioned in the URL (/v1/...). All v1 endpoints are stable per the public API versioning policy. SDKs at any 0.x or 1.x version can call any v1 endpoint that exists at request time; we don't couple SDK MAJOR to server MAJOR.

We add new endpoints under /v1/... additively. When we have to break, we add /v2/... and run both in parallel for at least a year. SDKs adopt the v2 endpoint in a MINOR release; the new endpoint becomes the default in the next SDK MAJOR.

See also

• Concept · Webhooks
• Reference · Webhook events
• All SDKs