WorkOS Docs Homepage
SDKs
API referenceDashboardSign In
SDKs

Ruby SDK

github.com
workos/ workos-ruby
38 Stars
33 Forks
61 Contributors
github.com
Official Ruby SDK for interacting with the WorkOS API.

Installation

Ruby

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 beta versions, refer to the README in the GitHub repository.

Releases

May 26, 2026

v9.0.0

Latest
May 26, 2026

Bug Fixes

⚠️ Breaking

  • organization_membership: Migrate organization membership to dedicated service
  • Moved organization membership methods from UserManagement to new OrganizationMembershipService class
  • Methods create_organization_membership, get_organization_membership, update_organization_membership, delete_organization_membership, deactivate_organization_membership, reactivate_organization_membership, list_organization_memberships, and list_organization_membership_groups now accessed via client.organization_membership instead of client.user_management
  • Removed UserManagement::RoleSingle and UserManagement::RoleMultiple data classes (moved to OrganizationMembershipService)
  • api_keys: Add expires_at field to API key models
  • Added expires_at optional field to ApiKey, OrganizationApiKey, OrganizationApiKeyWithValue, UserApiKey, and UserApiKeyWithValue models
  • Added expires_at field to CreateOrganizationApiKey and CreateUserApiKey request models
  • Updated create_organization_api_key and create_user_api_key methods to accept expires_at parameter
  • radar: Remove device_fingerprint and bot_score fields from Radar
  • Removed device_fingerprint and bot_score parameters from Radar.create_attempt method
  • Removed device_fingerprint and bot_score fields from RadarStandaloneAssessRequest model
  • Updated enum values in RadarStandaloneAssessRequestAction: removed LOGIN, SIGNUP, SIGN_UP_2, SIGN_IN_2, SIGN_IN_3, SIGN_UP_3; standardized to SIGN_UP and SIGN_IN
  • Removed CREDENTIAL_STUFFING and IP_SIGN_UP_RATE_LIMIT from RadarStandaloneResponseControl enum
  • audit_logs: Refactor audit logs models and type names
  • Merged AuditLogSchemaJson fields into AuditLogSchema; removed AuditLogSchemaJson class
  • Added new AuditLogSchemaInput class (write-side schema without read-only fields)
  • Renamed AuditLogSchemaJsonActor to AuditLogSchemaActorInput
  • Renamed AuditLogSchemaJsonTarget to AuditLogSchemaTargetInput
  • Removed AuditLogActionJson; AuditLogAction now extends BaseModel
  • Renamed AuditLogExportJson to AuditLogExport (now extends BaseModel)
  • Renamed AuditLogsRetentionJson to AuditLogsRetention (now extends BaseModel)
  • Removed AuditLogExportJsonState type; replaced with AuditLogExportState
  • Updated list_actions method return type from AuditLogActionJson to AuditLogAction
  • Updated create_export and get_export method return types from AuditLogExportJson to AuditLogExport
  • webhooks: Rename WebhookEndpointJson to WebhookEndpoint
  • Renamed WebhookEndpointJson to WebhookEndpoint
  • Updated list_webhook_endpoints, create_webhook_endpoint, and update_webhook_endpoint method return types
  • WebhookEndpointStatus is now an alias for UpdateWebhookEndpointStatus (no longer a standalone class); removed WebhookEndpointJsonStatus alias
  • Updated WebhookEndpoint to extend BaseModel for consistency
  • authorization: Add filtering parameters to authorization list methods
  • Added resource_id, resource_external_id, resource_type_slug filter parameters to list_role_assignments method
  • Added role_slug filter parameter to list_role_assignments_for_resource_by_external_id and list_role_assignments_for_resource methods
  • Removed search parameter from list_resources method

Features

  • vault: Add new Vault service with key-value operations
  • Added new Vault service class with methods: create_data_key, create_decrypt, create_rekey, list_kv, create_kv, get_name, get_kv, update_kv, delete_kv, list_kv_metadata, list_kv_versions
  • Added vault model classes: Actor, CreateDataKeyRequest, CreateDataKeyResponse, CreateObjectRequest, DecryptRequest, DecryptResponse, DeleteObjectResponse, ObjectModel, ObjectMetadata, ObjectSummary, ObjectVersion, ObjectWithoutValue, RekeyRequest, UpdateObjectRequest
  • Added VaultOrder enum for sorting operations
  • Added client.vault accessor to access the new service
  • pipes: Add Pipes connected account event models
  • Added PipeConnectedAccount model for representing connected accounts
  • Added three new event models: PipesConnectedAccountConnected, PipesConnectedAccountDisconnected, PipesConnectedAccountReauthorizationNeeded
  • Added PipeConnectedAccountState enum with CONNECTED and NEEDS_REAUTHORIZATION values
  • Added new webhook event types to CreateWebhookEndpointEvents and UpdateWebhookEndpointEvents
  • generated: Add Error and Actor shared models
  • Added Error model in shared module for error responses
  • Added Actor model in vault module representing user/actor information
  • Updated inflections to map 'object' to 'ObjectModel' to avoid conflicts
May 12, 2026

v8.0.1

May 12, 2026

v8.0.0...v8.0.1" rel="noreferrer" target="_blank">8.0.1 (2026-05-12)

Bug Fixes

May 6, 2026

v8.0.0

May 6, 2026

v7.1.2...v8.0.0" rel="noreferrer" target="_blank">8.0.0 (2026-05-06)

⚠ BREAKING CHANGES

  • authorization: Consolidate order enums to PaginationOrder
  • api_keys: Separate organization and user API key types
  • user_management: Consolidate order enums to PaginationOrder
  • vault: Add BYOK key deleted event and consolidate key provider enum
  • types: Consolidate pagination order enums
  • authorization: Rename RoleAssignment to UserRoleAssignment

Features

May 6, 2026

v7.1.2

May 6, 2026

v7.1.1...v7.1.2" rel="noreferrer" target="_blank">7.1.2 (2026-05-06)

Bug Fixes

April 29, 2026

v7.1.1

April 29, 2026

v7.1.0...v7.1.1" rel="noreferrer" target="_blank">7.1.1 (2026-04-29)

Bug Fixes

--- This PR was generated with Release Please. See documentation.

April 27, 2026

v7.1.0

April 27, 2026

v7.0.0...v7.1.0" rel="noreferrer" target="_blank">7.1.0 (2026-04-27)

Features

Bug Fixes

April 20, 2026

v7.0.0

April 20, 2026

This is a major release that introduces a fully redesigned SDK architecture. The SDK is now generated from the WorkOS OpenAPI spec, bringing type safety, consistent interfaces, and improved developer ergonomics.

High-Level Changes

  • Client-centric architecture: The SDK now revolves around an instantiated WorkOS::Client rather than module-level service calls. All product areas are accessed through client methods (e.g., client.organizations, client.user_management, client.sso).
  • Generated request/response models: Typed models replace raw hashes. Response models no longer inherit from Hash — use accessor methods instead of bracket notation.
  • Per-request overrides: The new runtime supports request_options: for per-request API key, timeout, base URL, and retry overrides — useful for multi-tenant setups.
  • Minimum Ruby 3.3+: The minimum Ruby version has been raised to 3.3.
  • Renamed services and methods: Several top-level services were renamed (e.g., WorkOS::Portal → client.admin_portal, WorkOS::MFA → client.multi_factor_auth). Method signatures now use explicit keyword arguments.
  • Session management refactor: AuthKit session sealing, refresh, and authentication flows were overhauled with a dedicated SessionManager on the client instance.
  • New capabilities: Device code flow, public/PKCE clients, auto_paging_each pagination, and last_response observability on all responses.

Migration Guide

For detailed instructions on updating your application, see the https://github.com/workos/workos-ruby/blob/main/docs/V7_MIGRATION_GUIDE.md" rel="noreferrer" target="_blank">v7 Migration Guide.

March 6, 2026

v6.2.0

March 6, 2026

v6.1.0...v6.2.0" rel="noreferrer" target="_blank">6.2.0 (2026-03-06)

Features

Bug Fixes

February 10, 2026

v6.1.0

February 10, 2026

See CHANGELOG.md for details

What's Changed

  • Add release-please for automated releases by @workos-sdk-automation[bot] in #435
  • fix: add invitation_token parameter to authentication methods by @gjtorikian in #438
  • Update amannn/action-semantic-pull-request action to v6 by @renovate[bot] in #436
  • chore(main): release workos 6.1.0 by @workos-sdk-automation[bot] in #437
  • fix: use simple v-prefixed tags and fix gem publish path by @workos-sdk-automation[bot] in #441
  • fix: revert VERSION extraction to handle simple v-prefixed tags by @workos-sdk-automation[bot] in #442

Full Changelog: v6.0.0...v6.1.0

February 4, 2026

v6.0.0

February 4, 2026

What's Changed

  • Add Rakefile to fix release workflow by @workos-sdk-automation[bot] in #426
  • Use gem-push-command to skip git push in release workflow by @workos-sdk-automation[bot] in #427
  • Fix release workflow to use OIDC credentials directly by @workos-sdk-automation[bot] in #429
  • Update actions/create-github-app-token action to v2 by @renovate[bot] in #422
  • Update peter-evans/create-pull-request action to v8 by @renovate[bot] in #424
  • Add ability to extract custom claims from the JWT during authentication by @adam-h in #431
  • Upgrade jwt gem from ~> 2.8 to ~> 3.1 by @workos-sdk-automation[bot] in #433
  • Allow pluggable encryptors for session seal/unseal by @gjtorikian in #432
  • v6.0.0 by @workos-sdk-automation[bot] in #434

Full Changelog: v5.31.1...v6.0.0

February 3, 2026

v5.31.1

February 3, 2026

What's Changed

  • Add custom_attributes field to OrganizationMembership by @ajworkos in #419
  • v5.31.1 by @workos-sdk-automation[bot] in #420
  • Update actions/checkout action to v6 by @renovate[bot] in #421
  • Add rake as a development dependency by @gjtorikian in #423

New Contributors

  • @ajworkos made their first contribution in #419

Full Changelog: v5.31.0...v5.31.1

January 15, 2026

v5.31.0

January 15, 2026

What's Changed

  • Add context7.json to repo by @nicknisi in #413
  • Update ruby/setup-ruby action to v1.281.0 by @renovate[bot] in #358
  • Update actions/checkout action to v6 by @renovate[bot] in #409
  • Update CODEOWNERS to point to the right Rubyist Team by @gjtorikian in #416
  • Bump rexml from 3.4.1 to 3.4.2 by @dependabot[bot] in #395
  • Add list sessions to user management by @adam-h in #415
  • 💎 5.31.0 by @gjtorikian in #418

New Contributors

  • @gjtorikian made their first contribution in #416

Full Changelog: v5.30.1...v5.31.0

December 2, 2025

v5.30.1

December 2, 2025

What's Changed

  • Version bump v5.30.1 by @kendallstrautman in #412
  • Multiple roles support: Add roles to SSO profile and directory user by @kendallstrautman in #411

Full Changelog: v5.29.0...v5.30.1

December 2, 2025

v5.30.0

December 2, 2025

⚠️ Misconfigured release version. Use v5.30.1 instead

In this version, the package semver was not updated properly and still references v5.29.0

What's Changed

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

Full Changelog: v5.29.0...v5.30.0

November 21, 2025

v5.29.0

November 21, 2025

What's Changed

  • expose authentication object even if expired by @ollym in #398

New Contributors

  • @ollym made their first contribution in #398

Full Changelog: v5.28.0...v5.29.0

November 20, 2025

v5.28.0

November 20, 2025

What's Changed

  • Add ability to resend invitations by @antn in #404
  • Fix reset_password to handle wrapped API response by @nicknisi in #406

New Contributors

  • @antn made their first contribution in #404

Full Changelog: v5.27.0...v5.28.0

October 27, 2025

v5.27.0

October 27, 2025

What's Changed

Full Changelog: v5.26.0...v5.27.0

October 10, 2025

v5.26.0

October 10, 2025

What's Changed

  • Add SSO and Domain Verification widget scopes by @adam-h in #396
  • AuthKit multiple roles support by @csrbarber in #397
  • Bump to 5.26.0 by @csrbarber in #399

New Contributors

  • @csrbarber made their first contribution in #397

Full Changelog: v5.25.0...v5.26.0

August 5, 2025

v5.25.0

August 5, 2025

What's Changed

  • Add GET /organizations/:orgId/feature-flags support by @stanleyphu in #391
  • v5.25.0 by @stanleyphu in #393

New Contributors

  • @stanleyphu made their first contribution in #391

Full Changelog: v5.24.0...v5.25.0

July 30, 2025

v5.24.0

July 30, 2025

What's Changed

  • Add screen_hint to Ruby Gem + vcr 6 by @Teyler7 in #389
  • v5.24.0 by @nholden in #390

Full Changelog: v5.23.0...v5.24.0

July 23, 2025

v5.23.0

July 23, 2025

What's Changed

  • Add external_id to user and organization in #381

Full Changelog: v5.22.0...v5.23.0

July 22, 2025

v5.22.0

July 22, 2025

What's Changed

  • Include decoded Feature Flags from the JWT into the payload of a WorkOS Session by @vdyalex in #386
  • Fix request body construction to only send non-nil values by @nicknisi in #384
  • Fix SSO error handling to surface detailed validation errors by @nicknisi in #385

New Contributors

  • @vdyalex made their first contribution in #386

Full Changelog: v5.21.0...v5.22.0

July 7, 2025

v5.21.0

July 7, 2025

What's Changed

  • user: allow updating external_id, add to User object by @mxlje in #378
  • Add permissions to Role by @andrewhampton in #382

New Contributors

  • @mxlje made their first contribution in #378
  • @andrewhampton made their first contribution in #382

Full Changelog: v5.20.0...v5.21.0

June 23, 2025

v5.20.0

June 23, 2025

What's Changed

Full Changelog: v5.19.0...v5.20.0

May 29, 2025

v5.19.0

May 29, 2025

What's Changed

  • add missing session param to authenticate_with methods by @jameslcarpino in #375

New Contributors

  • @jameslcarpino made their first contribution in #375

Full Changelog: v5.18.0...v5.19.0

May 22, 2025

v5.18.0

May 22, 2025

What's Changed

  • Added support for email in UserManagement.update_user (#365)
April 25, 2025

v5.17.1

April 25, 2025

What's Changed

  • Bump rexml from 3.2.6 to 3.4.1 by @alexandrule in #359
  • v5.17.1 by @nicknisi in #364

New Contributors

  • @alexandrule made their first contribution in #359

Full Changelog: v5.17.0...v5.17.1

April 24, 2025

v5.17.0

April 24, 2025

What's Changed

Full Changelog: v5.16.1...v5.17.0

April 23, 2025

v5.16.1

April 23, 2025

What's Changed

  • Pin third-party actions to currently used SHA by @nickcollisson-workos in #357
  • Bump rexml from 3.2.6 to 3.3.3 by @dependabot in #318
  • v5.16.1 by @nicknisi in #362

New Contributors

  • @nickcollisson-workos made their first contribution in #357

Full Changelog: v5.16.0...v5.16.1

March 21, 2025

v5.16.0

March 21, 2025

What's Changed

  • Add email standard attribute to DirectoryUser
  • Mark emails, job_title, and username standard attributes as deprecated. Enable the equivalent auto-mapped custom attributes instead (https://github.com/workos/workos-ruby/pull/355" rel="noreferrer" target="_blank">#413)

Full Changelog: v5.15.0...v5.16.0