WorkOS Docs Homepage
SDKs
API referenceDashboardSign In
SDKs

Java SDK

github.com
workos/workos-kotlin
18 Stars
9 Forks
36 Contributors
github.com
Official Java SDK for interacting with the WorkOS API.

Installation

Java

Beta Versions

Certain WorkOS features may be available only in the beta version of the SDK. Beta versions have the -beta.* suffix, for example, 3.2.0-beta.1. For more information on how to use the beta versions, refer to the README in the GitHub repository.

Releases

May 6, 2026

v5.0.0

Latest
May 6, 2026

⚠ BREAKING CHANGES

  • Release the next major SDK version (#357)
  • Upgrade to Java 17 and migrate any Fuel-based HTTP customization to OkHttpClient
  • Recreate WorkOS clients with constructor-based configuration instead of mutating apiHostname, https, or port
  • Update service accessors and method names across the SDK, including renamed services such as PortalApi -> AdminPortal, MfaApi -> MultiFactorAuth, and FgaApi -> Authorization
  • Replace per-service model, type, and builder imports with the consolidated shared packages and newer flat method arguments or option classes
  • Adopt the new pagination, webhook verification, and request handling patterns used across v5
  • Review any existing FGA integrations closely, since the v5 Authorization API is a redesign rather than a direct rename

Features

  • Release the next major SDK version (#357) (0b2b9e8)
  • Regenerate service clients from the OpenAPI spec and standardize retries, pagination, request overrides, and error handling across the SDK
  • Consolidate generated models and enums into shared packages to reduce service-specific surface area
  • Move webhook signature verification to the standalone Webhook helper while keeping webhook endpoint management on the Webhooks service

Please read the v5 migration guide before upgrading: https://github.com/workos/workos-kotlin/blob/v5.0.0/docs/V5_MIGRATION_GUIDE.md

Full Changelog: v4.25.0...v5.0.0

May 1, 2026

v4.25.0

May 1, 2026

4.25.0 (2026-04-30)

Features

April 30, 2026

v4.24.0

April 30, 2026

4.24.0 (2026-04-30)

Features

  • Add user to organization membership response (#369) (de6e1c4)
  • Add Authorization (FGA) API endpoints (#353) (23fdabd)
  • Add custom_attributes field to OrganizationMembership (#306) (7e4643e)
  • Add email field to DirectoryUser (#321) (f6defcb)
  • Add missing event models, types, and tests (#347) (9f1ec27)
  • add organization_id to OrganizationDomain model (#350) (a261a3e)
  • add release-please for automated releases (#322) (087273f)
  • Add resourceExternalId optional filter param for listAuthorizationResources (#368) (2219cf6)
  • user-management: add directoryManaged to OrganizationMembership (#336) (b0ad0d3)

Bug Fixes

  • Add missing portal intents (#345) (912e64d)
  • Add organization domain verification webhook events (#346) (f92ac24)
  • Make UserUpdated extend User for dsync.user.updated events (#334) (7b1782f)
  • remove @JsonCreator from all-default-param classes for Jackson 2.21.x compatibility (#354) (118d1b3)
  • Remove extractVersion from matchUpdateTypes rules (#366) (581225c)
  • serialize list query params as comma-separated lowercase values (#355) (f62826c)
  • update renovate rules (#319) (740b5fa)
  • use explicit JsonCreator.Mode.PROPERTIES for Jackson 2.21.0 compatibility (#348) (52aed90)
April 23, 2026

v4.23.0

April 23, 2026

4.23.0 (2026-04-23)

Features

  • Add resourceExternalId optional filter param for listAuthorizationResources (#368) (2219cf6)

Bug Fixes

  • Remove extractVersion from matchUpdateTypes rules (#366) (581225c)
April 8, 2026

workos: v4.22.0

April 8, 2026

4.22.0 (2026-04-08)

Features

  • Add Authorization (FGA) API endpoints (#353) (23fdabd)
  • add organization_id to OrganizationDomain model (#350) (a261a3e)

Bug Fixes

  • remove @JsonCreator from all-default-param classes for Jackson 2.21.x compatibility (#354) (118d1b3)
  • serialize list query params as comma-separated lowercase values (#355) (f62826c)
March 26, 2026

workos: v4.21.0

March 26, 2026

4.21.0 (2026-03-26)

Features

  • Add missing event models, types, and tests (#347) (9f1ec27)

Bug Fixes

  • Add organization domain verification webhook events (#346) (f92ac24)
  • use explicit JsonCreator.Mode.PROPERTIES for Jackson 2.21.0 compatibility (#348) (52aed90)
March 24, 2026

workos: v4.20.0

March 24, 2026

4.20.0 (2026-03-24)

Features

  • user-management: add directoryManaged to OrganizationMembership (#336) (b0ad0d3)

Bug Fixes

March 4, 2026

workos: v4.19.1

March 4, 2026

4.19.1 (2026-03-04)

Bug Fixes

  • Make UserUpdated extend User for dsync.user.updated events (#334) (7b1782f)
February 26, 2026

workos: v4.19.0

February 26, 2026

4.19.0 (2026-02-26)

Features

  • Add custom_attributes field to OrganizationMembership (#306) (7e4643e)
  • Add email field to DirectoryUser (#321) (f6defcb)
  • add release-please for automated releases (#322) (087273f)

Bug Fixes

December 3, 2025

v4.18.1

December 3, 2025

What's Changed

  • Bump version 4.18.1 by @kendallstrautman in #304
  • Multiple roles support: Add roles property to directory user and SSO profile by @kendallstrautman in #302

Full Changelog: v4.17.0...v4.18.1

December 2, 2025

v4.18.0

December 2, 2025

⚠️ Misconfigured release version. Use v4.18.1 instead

In this version, the package semver was not updated properly and still references v4.17.0

What's Changed

  • Multiple roles support: Add roles property to directory user and SSO profile by @kendallstrautman in #302

Full Changelog: v4.17.0...v4.18.0

November 21, 2025

v4.17.0

November 21, 2025

What's Changed

  • Add ability to resend invitation by @antn in #299

New Contributors

  • @antn made their first contribution in #299

Full Changelog: v4.16.0...v4.17.0

October 10, 2025

v4.16.0

October 10, 2025

What's Changed

  • Update Nexus publishing endpoints by @nicknisi in #296
  • Add multiple roles support for OrganizationMemberships by @csrbarber in #295
  • v4.16.0 by @csrbarber in #297

New Contributors

  • @csrbarber made their first contribution in #295

Full Changelog: v4.15.0...v4.16.0

September 29, 2025

v4.15.0

September 29, 2025

Added

  • Added Events API Support (#292)
  • Added Invitation Accepted, Revoked Events (#291)

Fixed

  • Fixed OAuth error response mapping for authentication endpoints (#290)
June 23, 2025

v4.14.0

June 23, 2025

What's Changed

  • Added email to UpdateUserOptions (#281)
  • Added user webhook events (#284)
  • Added support for custom scopes (#285)

Full Changelog: v4.13.0...v4.14.0

May 20, 2025

v4.13.0

May 20, 2025

What's Changed

  • adding "deleting" to connectionState enums by @rarevalo13 in #278
  • Add warnings to FGA check and query responses by @atainter in #280
  • Bump to v4.13.0 by @rarevalo13 in #279

New Contributors

  • @rarevalo13 made their first contribution in #278
  • @atainter made their first contribution in #280

Full Changelog: v4.12.0...v4.13.0

May 2, 2025

v4.12.0

May 2, 2025

What's Changed

  • Add customAttributes field to SSO Profile (#275)

Full Changelog: v4.11.0...v4.12.0

April 10, 2025

v4.11.0

April 10, 2025

What's Changed

  • Added password_reset.succeeded event type (#273)

Full Changelog: v4.10.0...v4.11.0

March 28, 2025

v4.10.0

March 28, 2025

What's Changed

  • Add email standard attribute to DirectoryUser (#270)
  • Mark emails, job_title, and username standard attributes as deprecated. Enable the equivalent auto-mapped custom attributes instead (#270)

Full Changelog: v4.9.0...v4.10.0

February 21, 2025

v4.9.0

February 21, 2025

What's Changed

  • Added state, verificationStrategy, and verificationToken to OrganizationDomain (#266)
  • Added lastSignInAt to User (#268)

Full Changelog: v4.8.0...v4.9.0

January 15, 2025

v4.8.0

January 15, 2025

Added

  • Added optional returnTo parameter to getLogoutUrl (#264)

Full Changelog: v4.7.0...v4.8.0

January 6, 2025

v4.7.0

January 6, 2025

Added

  • Add GET /organization/:orgId/roles API support (#262)

Full Changelog: v4.6.1...v4.7.0

December 11, 2024

v4.6.1

December 11, 2024

Fixed

  • Make role attribute optional on directorysync.models.User by @jonatascastro12 in #259

Full Changelog: v4.6.0...v4.6.1

November 15, 2024

v4.6.0

November 15, 2024

Added

  • Add widgets get token API support (#257)

Full Changelog: v4.5.0...v4.6.0

October 21, 2024

v4.5.0

October 21, 2024

What's Changed

  • Add role to directory user by @kendallstrautman in #254

Full Changelog: v4.4.0...v4.5.0

October 17, 2024

v4.4.0

October 17, 2024

What's Changed

  • Add ProfileRole property in #252

Full Changelog: v4.3.1...v4.4.0

September 13, 2024

v4.3.1

September 13, 2024

Fixed

  • Fixed FGA query method to make correct requests #250
August 26, 2024

v4.3.0

August 26, 2024

Added

  • Added support for authentication.sso_failed and authentication.oauth_failed events (#248)
August 14, 2024

v4.2.1

August 14, 2024

Added

  • Add warrant token support to listWarrants [#246]
August 14, 2024

v4.2.0

August 14, 2024

Added

  • Add support for FGA endpoints with request retries (#244)