WorkOS Ruby

https://github.com/workos/workos-ruby
Admin
WorkOS Ruby is a library that provides convenient access to the WorkOS API for building...
Tokens:43,500
Snippets:451
Trust Score:10
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Create User Example

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/user-management.md

A complete example of creating a user with metadata and a plaintext password.

```ruby
user = WorkOS.client.user_management.create_user(
  email: "marceline@example.com",
  first_name: "Marceline",
  last_name: "Abadeer",
  password: WorkOS::UserManagement::PasswordPlaintext.new(password: "InitialPass123!"),
  metadata: {department: "Engineering"}
)

puts user.id  # => "user_..."
```

--------------------------------

### Multi-tenant Admin Setup

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/admin-portal.md

Generates multiple setup links for an organization and returns them via an API response.

```ruby
def setup_organization(tenant_id)
  org = Organization.find(tenant_id)

  # Generate links for all setup flows
  setup_links = {
    sso: WorkOS.client.admin_portal.generate_link(
      organization: org.workos_id,
      intent: "sso",
      success_url: "https://#{org.domain}/setup/complete?step=sso"
    ),
    dsync: WorkOS.client.admin_portal.generate_link(
      organization: org.workos_id,
      intent: "dsync",
      success_url: "https://#{org.domain}/setup/complete?step=dsync"
    )
  }

  # Return setup URLs
  {
    sso_setup_url: setup_links[:sso].link,
    dsync_setup_url: setup_links[:dsync].link
  }
end

# In API response
render json: {
  setup_urls: setup_organization(params[:tenant_id])
}
```

--------------------------------

### Client Configuration Patterns

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/client.md

Examples for using the WorkOS Ruby client in singleton or multi-tenant environments.

```APIDOC
## Client Configuration

### Singleton Pattern
Configure the global client using `WorkOS.configure`.

### Multi-tenant Pattern
Instantiate multiple `WorkOS::Client` instances with unique API keys and client IDs for different tenants.
```

--------------------------------

### Example Log Output

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/configuration.md

Sample output format when debug logging is enabled.

```text
D, [2024-01-15T10:30:45.123456] DEBUG -- : request start method="GET" path="/organizations" attempt=1
D, [2024-01-15T10:30:45.234567] DEBUG -- : response status=200 latency_ms=111 request_id="req_123"
```

--------------------------------

### Install WorkOS gem

Source: https://github.com/workos/workos-ruby/blob/main/README.md

Use the gem command to install the WorkOS library.

```sh
gem install workos
```

--------------------------------

### Generate Admin Portal Link Example

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/admin-portal.md

Creates an authenticated link for an organization and redirects the user to the portal.

```ruby
response = WorkOS.client.admin_portal.generate_link(
  organization: "org_123",
  intent: "sso",
  return_url: "https://app.example.com/dashboard"
)

# Redirect user to portal
redirect_to response.link
```

--------------------------------

### Enroll an MFA Factor in Ruby

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/multi-factor-auth.md

Use these examples to enroll either an SMS or TOTP authentication factor for a user.

```ruby
factor = WorkOS.client.multi_factor_auth.enroll_factor(
  type: "sms",
  phone_number: "+1234567890",
  user_id: "user_123"
)

puts factor.id
puts factor.type  # => "sms"
```

```ruby
factor = WorkOS.client.multi_factor_auth.enroll_factor(
  type: "totp",
  totp_issuer: "MyApp",
  totp_user: "user@example.com",
  user_id: "user_123"
)

puts factor.totp_qr_code  # Base64-encoded QR code image
```

--------------------------------

### Get an organization

Source: https://github.com/workos/workos-ruby/blob/main/README.md

Fetch details for a specific organization by its unique identifier.

```ruby
organization = WorkOS.client.organizations.get_organization(id: "org_123")
puts organization.name
```

--------------------------------

### Get Directory User

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/directory-sync.md

Fetches details for a specific user by its ID. Throws WorkOS::NotFoundError if the user is not found.

```ruby
client.directory_sync.get_user(
  id: String,
  request_options: Hash = {}
) -> WorkOS::DirectoryUser
```

```ruby
user = WorkOS.client.directory_sync.get_user(id: "dir_usr_123")
puts user.email
puts user.first_name
puts user.last_name
```

--------------------------------

### WorkOS::Client.new

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/client.md

Initializes a new WorkOS client instance with the required API credentials and optional configuration settings.

```APIDOC
## WorkOS::Client.new

### Description
Initializes a new WorkOS client instance. This client acts as the central hub for accessing all WorkOS service modules.

### Parameters
- **api_key** (String) - Required - WorkOS API key for authentication (format: sk_...)
- **base_url** (String) - Optional - API endpoint URL (default: "https://api.workos.com")
- **client_id** (String) - Optional - OAuth client ID for AuthKit and SSO flows
- **timeout** (Integer) - Optional - Request timeout in seconds (default: 30)
- **max_retries** (Integer) - Optional - Maximum number of automatic retries for transient failures (default: 2)
- **logger** (Logger) - Optional - Optional logger instance for debug output
- **log_level** (Symbol) - Optional - Log level: :debug, :info, :warn, :error
```

--------------------------------

### Initialize Multi-Tenant Clients

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/configuration.md

Create a hash of WorkOS::Client instances mapped to specific tenant configurations.

```ruby
tenants = {
  "tenant_a" => {key: "sk_tenant_a_key", id: "client_a_id"},
  "tenant_b" => {key: "sk_tenant_b_key", id: "client_b_id"}
}

@clients = tenants.transform_values do |config|
  WorkOS::Client.new(
    api_key: config[:key],
    client_id: config[:id],
    timeout: 60
  )
end

# Use per tenant
org_a = @clients["tenant_a"].organizations.list_organizations
org_b = @clients["tenant_b"].organizations.list_organizations
```

--------------------------------

### Initialize Multi-tenant Clients

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/README.md

Create separate client instances for different tenants to manage distinct API keys.

```ruby
@clients = {
  "tenant_a" => WorkOS::Client.new(api_key: key_a),
  "tenant_b" => WorkOS::Client.new(api_key: key_b)
}
@clients["tenant_a"].organizations.list_organizations
```

--------------------------------

### Initialize WorkOS Client

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/client.md

Instantiate the client with your API key and optional configuration parameters like timeout or retry settings.

```ruby
WorkOS::Client.new(
  api_key: String,
  base_url: String = "https://api.workos.com",
  client_id: String = nil,
  timeout: Integer = 30,
  max_retries: Integer = 2,
  logger: Logger = nil,
  log_level: Symbol = nil
)
```

--------------------------------

### Get Organization

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/organizations.md

Retrieve a single organization by its unique ID. Throws WorkOS::NotFoundError if the organization does not exist.

```ruby
org = WorkOS.client.organizations.get_organization(id: "org_123")
puts org.name
puts org.created_at
```

--------------------------------

### Initialize PublicClient

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/client.md

Constructor signature for creating a PublicClient instance.

```ruby
PublicClient.create(client_id: String) -> PublicClient
```

--------------------------------

### Recommended Environment Variables

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/configuration.md

List of environment variables used for SDK configuration.

```bash
# Required
WORKOS_API_KEY=sk_...

# Optional
WORKOS_CLIENT_ID=client_...
WORKOS_BASE_URL=https://api.workos.com
WORKOS_REQUEST_TIMEOUT=30
WORKOS_MAX_RETRIES=2

# For webhooks
WORKOS_WEBHOOK_SECRET=secret_...

# For session manager (sealed cookies)
WORKOS_SESSION_COOKIE_PASSWORD=$(ruby -rsecurerandom -e 'puts SecureRandom.base64(32)')
```

--------------------------------

### Get Organization Group

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/groups-authorization.md

Retrieves details for a specific group. Throws WorkOS::NotFoundError if the group does not exist.

```ruby
client.groups.get_organization_group(
  organization_id: String,
  group_id: String,
  request_options: Hash = {}
) -> WorkOS::Group
```

```ruby
group = WorkOS.client.groups.get_organization_group(
  organization_id: "org_123",
  group_id: "group_456"
)

puts group.name
```

--------------------------------

### Use Singleton Client Pattern

Source: https://github.com/workos/workos-ruby/blob/main/README.md

The recommended approach for most applications using a single WorkOS configuration.

```ruby
WorkOS.configure do |config|
  config.api_key = ENV.fetch("WORKOS_API_KEY")
  config.client_id = ENV["WORKOS_CLIENT_ID"]
end

WorkOS.client.organizations.list_organizations
```

--------------------------------

### Configure WorkOS SDK

Source: https://github.com/workos/workos-ruby/blob/main/README.md

Initialize the SDK with API keys and client IDs. The SDK does not read environment variables automatically.

```ruby
# /config/initializers/workos.rb

require "workos"

WorkOS.configure do |config|
  config.api_key = ENV.fetch("WORKOS_API_KEY")
  config.client_id = ENV["WORKOS_CLIENT_ID"]
  config.timeout = 120
  config.logger = Logger.new($stdout)
  config.log_level = :info
end

client = WorkOS.client
```

--------------------------------

### Get organization audit log retention in Ruby

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/audit-logs.md

Fetches the current retention policy for a specific organization by its ID.

```ruby
retention = WorkOS.client.audit_logs.get_organization_audit_logs_retention(id: "org_123")
puts "Retention period: #{retention.retention_period_in_days} days"
```

--------------------------------

### Get Directory Group

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/directory-sync.md

Fetches details for a specific group by its ID. Throws WorkOS::NotFoundError if the group is not found.

```ruby
client.directory_sync.get_group(
  id: String,
  request_options: Hash = {}
) -> WorkOS::DirectoryGroup
```

```ruby
group = WorkOS.client.directory_sync.get_group(id: "dir_grp_123")
puts group.name
puts group.member_ids
```

--------------------------------

### Configure Singleton Client

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/README.md

Recommended for most applications to reuse a single client instance.

```ruby
WorkOS.configure { |c| c.api_key = ENV["WORKOS_API_KEY"] }
WorkOS.client.organizations.list_organizations  # Reuses same client
```

--------------------------------

### Instantiate WorkOS::PublicClient

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/configuration.md

Initialize a client for browser, mobile, or CLI applications that do not use server-side credentials.

```ruby
public_client = WorkOS::PublicClient.create(client_id: "client_123")

# Use PKCE flow for OAuth (no client_secret)
url, verifier, state = public_client.user_management.get_authorization_url_with_pkce(
  provider: "authkit",
  redirect_uri: "https://example.com/callback"
)
```

--------------------------------

### SDK File Organization

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/README.md

Overview of the library directory structure including services, models, and utility classes.

```text
lib/workos/
  client.rb                   # Main client (service accessors)
  base_client.rb              # HTTP transport, retries
  configuration.rb            # Global configuration
  
  organizations.rb            # Organizations service
  user_management.rb          # Users & authentication
  sso.rb                       # SSO connections
  groups.rb                    # User groups
  authorization.rb            # RBAC and role assignments
  audit_logs.rb              # Audit events
  webhooks.rb                # Webhook management
  multi_factor_auth.rb       # MFA factors
  feature_flags.rb           # Feature flags
  
  organization.rb            # Models (one per resource type)
  user.rb
  connection.rb
  group.rb
  ...
  
  types/
    base_model.rb            # Base class for all models
    list_struct.rb           # Pagination wrapper
    api_response.rb          # Response metadata
    *_type.rb               # Type definitions and enums
  
  errors.rb                  # Error classes
  util/
    signature.rb            # Signature verification
```

--------------------------------

### Initialize Public Client for PKCE

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/README.md

Use for browser or mobile applications requiring PKCE authorization flows.

```ruby
public_client = WorkOS::PublicClient.create(client_id: "client_123")
url, verifier, state = public_client.user_management.get_authorization_url_with_pkce(...)
```

--------------------------------

### WorkOS::PublicClient.create

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/client.md

Initializes a new PublicClient instance for browser, mobile, or CLI applications using PKCE authentication.

```APIDOC
## WorkOS::PublicClient.create

### Description
Creates a client instance for environments without server-side secrets, utilizing PKCE for OAuth flows.

### Signature
`PublicClient.create(client_id: String) -> PublicClient`

### Parameters
- **client_id** (String) - Required - Public OAuth client ID
```

--------------------------------

### Set up Webhooks in Rails

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/webhooks.md

Implementation of a Rails controller and background job to handle and verify incoming WorkOS webhooks.

```ruby
# config/initializers/workos.rb
WorkOS.configure do |config|
  config.api_key = ENV.fetch("WORKOS_API_KEY")
end

# app/controllers/webhooks_controller.rb
class WebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token, only: [:workos]

  def workos
    payload = request.body.read
    sig_header = request.headers["HTTP_WORKOS_SIGNATURE"]
    secret = ENV["WORKOS_WEBHOOK_SECRET"]

    begin
      event = WorkOS.client.webhooks.construct_event(
        payload: payload,
        sig_header: sig_header,
        secret: secret
      )

      # Process webhook asynchronously
      WebhookProcessorJob.perform_later(event)

      head :ok
    rescue WorkOS::SignatureVerificationError => e
      Rails.logger.warn "Webhook verification failed: #{e.message}"
      head :unauthorized
    rescue StandardError => e
      Rails.logger.error "Webhook processing error: #{e.message}"
      head :internal_server_error
    end
  end
end

# app/jobs/webhook_processor_job.rb
class WebhookProcessorJob < ApplicationJob
  def perform(event)
    case event["event"]
    when "user.created"
      User.sync_from_webhook(event["data"])
    when "user.updated"
      User.sync_from_webhook(event["data"])
    when "organization.created"
      Organization.sync_from_webhook(event["data"])
    end
  end
end

# config/routes.rb
post "webhooks/workos", to: "webhooks#workos"
```

--------------------------------

### Create User with Password Variants

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/user-management.md

Demonstrates creating users using either plaintext passwords or pre-hashed password objects.

```ruby
user = WorkOS.client.user_management.create_user(
  email: "alice@example.com",
  password: WorkOS::UserManagement::PasswordPlaintext.new(password: "SecurePass123")
)
```

```ruby
user = WorkOS.client.user_management.create_user(
  email: "bob@example.com",
  password: WorkOS::UserManagement::PasswordHashed.new(
    password_hash: "bcrypt_hash_here",
    password_hash_type: "bcrypt",
    password_salt_position: "suffix"  # or "prefix"
  )
)
```

--------------------------------

### Create a user

Source: https://github.com/workos/workos-ruby/blob/main/README.md

Create a new user record using the user_management client.

```ruby
user = WorkOS.client.user_management.create_user(
  email: "marceline@example.com",
  first_name: "Marceline",
  last_name: "Abadeer"
)

puts user.id
```

--------------------------------

### Create organization with SSO

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/README.md

Creates a new organization and configures a SAML connection using metadata.

```ruby
# 1. Create organization
org = WorkOS.client.organizations.create_organization(
  name: "Acme Corp",
  domain_data: [{domain: "acme.com"}]
)

# 2. Set up SSO
conn = WorkOS.client.sso.create_connection(
  organization_id: org.id,
  connection_type: "SAML",
  name: "Okta",
  saml_metadata: File.read("okta_metadata.xml")
)

# 3. Share WorkOS metadata with identity provider
puts "Configure SAML callback: #{conn.saml_acs_url}"
```

--------------------------------

### Set up team structure with roles in Ruby

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/groups-authorization.md

Creates organization groups and assigns specific roles to those groups using the WorkOS client.

```ruby
org_id = "org_123"

# Create groups
engineering = WorkOS.client.groups.create_organization_group(
  organization_id: org_id,
  name: "Engineering",
  description: "Engineering team"
)

marketing = WorkOS.client.groups.create_organization_group(
  organization_id: org_id,
  name: "Marketing",
  description: "Marketing team"
)

# Assign roles to groups
WorkOS.client.authorization.create_group_role_assignment(
  group_id: engineering.id,
  role_slug: "developer"
)

WorkOS.client.authorization.create_group_role_assignment(
  group_id: marketing.id,
  role_slug: "editor"
)

puts "Groups and roles configured"
```

--------------------------------

### Use Multi-tenant Client Pattern

Source: https://github.com/workos/workos-ruby/blob/main/README.md

Instantiate separate clients for different API keys to support multi-tenant architectures.

```ruby
tenant_a = WorkOS::Client.new(api_key: "sk_tenant_a", client_id: "client_a")
tenant_b = WorkOS::Client.new(api_key: "sk_tenant_b", client_id: "client_b")

tenant_a.organizations.list_organizations
tenant_b.organizations.list_organizations
```

--------------------------------

### Create an OAuth SSO connection

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/sso.md

Sets up an OAuth connection using client credentials. The returned redirect URI must be registered with the OAuth provider.

```ruby
oauth_config = {
  client_id: ENV["PROVIDER_CLIENT_ID"],
  client_secret: ENV["PROVIDER_CLIENT_SECRET"]
}

conn = WorkOS.client.sso.create_connection(
  organization_id: "org_123",
  connection_type: "OAuth",
  name: "GitHub Enterprise",
  oauth_metadata: oauth_config
)

# Redirect URI is: conn.oauth_redirect_uri
# Register this with OAuth provider
```

--------------------------------

### Implement multi-tenant client pattern

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/client.md

Instantiate separate WorkOS::Client objects for different tenants to manage distinct API keys and client IDs.

```ruby
tenants = {
  "tenant_a" => {key: "sk_tenant_a", id: "client_a"},
  "tenant_b" => {key: "sk_tenant_b", id: "client_b"}
}

@clients = tenants.transform_values do |creds|
  WorkOS::Client.new(api_key: creds[:key], client_id: creds[:id])
end

# Access by tenant
@clients["tenant_a"].organizations.list_organizations
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/configuration.md

Explicitly configure the SDK with environment variables as they are not read automatically.

```ruby
# Wrong — this does NOT work
# WorkOS will not read WORKOS_API_KEY automatically

# Correct — configure in initializer
WorkOS.configure do |config|
  config.api_key = ENV.fetch("WORKOS_API_KEY")
  config.client_id = ENV["WORKOS_CLIENT_ID"]
end
```

--------------------------------

### Manage roles and permissions

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/README.md

Creates a group, adds a user to it, and assigns a role to the group.

```ruby
# 1. Create group
group = WorkOS.client.groups.create_organization_group(
  organization_id: "org_123",
  name: "Admins"
)

# 2. Add users to group
WorkOS.client.groups.add_user_to_group(
  organization_id: "org_123",
  group_id: group.id,
  user_id: "user_456"
)

# 3. Assign role to group
WorkOS.client.authorization.create_group_role_assignment(
  group_id: group.id,
  role_slug: "admin"
)
```

--------------------------------

### WorkOS.configure

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/client.md

Configures the global WorkOS client settings.

```APIDOC
## WorkOS.configure

### Description
Sets global configuration options for the WorkOS SDK, including API keys, timeouts, and logging.

### Configuration Options
- **api_key** (String) - API key for authentication
- **client_id** (String) - Client ID for OAuth flows
- **timeout** (Integer) - Request timeout in seconds
- **max_retries** (Integer) - Number of retries for failed requests
- **logger** (Logger) - Logger instance
- **log_level** (Symbol) - Logging level
```

--------------------------------

### Set up audit logging

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/README.md

Configures webhook endpoints, verifies incoming event signatures, and logs custom audit events.

```ruby
# 1. Create webhook for events
endpoint = WorkOS.client.webhooks.create_webhook_endpoint(
  endpoint_url: "https://app.example.com/webhooks/workos",
  events: ["user.created", "organization.updated"]
)

# 2. Verify webhook signatures
event = WorkOS.client.webhooks.construct_event(
  payload: request.body.read,
  sig_header: request.headers["HTTP_WORKOS_SIGNATURE"],
  secret: ENV["WORKOS_WEBHOOK_SECRET"]
)

# 3. Log custom events
WorkOS.client.audit_logs.create_event(
  organization_id: "org_123",
  action: "payment.processed",
  actor_type: "user",
  actor_user_id: current_user.id,
  target_type: "payment",
  target_id: payment.id,
  metadata: {amount: 5000, currency: "USD"}
)
```

--------------------------------

### Generate Admin Portal Link for Custom Signing Keys

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/admin-portal.md

Creates a link for configuring custom signing keys.

```ruby
link = WorkOS.client.admin_portal.generate_link(
  organization: org_id,
  intent: "bring_your_own_key"
)
# User can configure custom keys
```

--------------------------------

### Initialize PasswordPlaintext

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/user-management.md

Used to provide a plaintext password that WorkOS will hash using bcrypt.

```ruby
WorkOS::UserManagement::PasswordPlaintext.new(password: String)
```

--------------------------------

### Initialize Session Manager

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/README.md

Create a session manager with a custom encryptor and seal a session. Ensure the password used for encryption meets the 32-byte high entropy requirement.

```ruby
session_manager = WorkOS.client.session_manager(
  encryptor: MyEncryptor.new(cookie_password)
)

sealed = session_manager.seal_session(
  user_id: "user_123",
  organization_id: "org_456",
  access_token: "token"
)
```

--------------------------------

### Create and update an organization

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/organizations.md

Create an organization with domain data and metadata, then update specific fields like metadata later.

```ruby
org = WorkOS.client.organizations.create_organization(
  name: "Tech Startup Inc",
  domain_data: [
    {domain: "techstartup.com"},
    {domain: "ts.com"}
  ],
  metadata: {
    tier: "enterprise",
    region: "us-east-1"
  },
  external_id: "cust_ts_001"
)

# Later, update tier
updated = WorkOS.client.organizations.update_organization(
  id: org.id,
  metadata: {tier: "professional"}
)
```

--------------------------------

### Handle MFA during login

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/multi-factor-auth.md

Demonstrates a two-step authentication flow where a user is prompted for an MFA code if required by the initial authentication response.

```ruby
def authenticate
  response = WorkOS.client.user_management.create_authenticate(
    client_id: ENV["WORKOS_CLIENT_ID"],
    grant_type: "password",
    client_secret: ENV["WORKOS_CLIENT_SECRET"],
    email: params[:email],
    password: params[:password]
  )

  if response.authentication_challenge
    # MFA required
    session[:mfa_challenge_id] = response.authentication_challenge.id
    session[:auth_user_id] = response.user.id  # May be partial/pending

    # Prompt for MFA code
    render :mfa_challenge, locals: {factor_type: response.authentication_challenge.auth_factor_type}
  else
    # No MFA needed; complete login
    session[:user_id] = response.user.id
    session[:access_token] = response.access_token
    redirect_to dashboard_path
  end
end

def verify_mfa
  challenge_id = session.delete(:mfa_challenge_id)
  code = params[:mfa_code]

  result = WorkOS.client.multi_factor_auth.verify_challenge(
    id: challenge_id,
    code: code
  )

  if result.valid
    # Get new access token with MFA satisfied
    auth_response = WorkOS.client.user_management.create_authenticate(
      client_id: ENV["WORKOS_CLIENT_ID"],
      grant_type: "mfa",
      authentication_challenge_id: challenge_id,
      code: code
    )

    session[:user_id] = auth_response.user.id
    session[:access_token] = auth_response.access_token
    redirect_to dashboard_path
  else
    flash[:error] = "Invalid verification code"
    render :mfa_challenge
  end
end
```

--------------------------------

### WorkOS.client

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/client.md

Retrieves the singleton global client instance.

```APIDOC
## WorkOS.client

### Description
Returns the singleton global client instance, lazily initialized based on the current configuration.
```

--------------------------------

### Create a SAML SSO connection

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/sso.md

Initializes a SAML connection by providing organization ID and IdP metadata. The resulting object provides the necessary URLs for IdP configuration.

```ruby
# 1. Get metadata from identity provider (Okta, Azure AD, etc.)
idp_metadata = File.read("/path/to/okta_metadata.xml")

# 2. Create connection
conn = WorkOS.client.sso.create_connection(
  organization_id: "org_123",
  connection_type: "SAML",
  name: "Okta Production",
  saml_metadata: idp_metadata
)

# 3. Extract WorkOS settings to configure IdP callback
puts "Configuration URL: #{conn.saml_metadata_url}"
puts "ACS URL (callback): #{conn.saml_acs_url}"
puts "Entity ID: #{conn.saml_entity_id}"

# 4. Share metadata URL with IdP administrator
# IdP downloads: conn.saml_metadata_url
```

--------------------------------

### Initialize OrganizationDomainData

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/organizations.md

Creates a new domain data object for use in organization creation or update requests.

```ruby
WorkOS::OrganizationDomainData.new(
  domain: String,
  verification_state: String = "pending"
)
```

--------------------------------

### Create a User with Ruby

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/user-management.md

Defines the method signature for creating a new user in the WorkOS system.

```ruby
client.user_management.create_user(
  email: String,
  first_name: String = WorkOS::OMIT,
  last_name: String = WorkOS::OMIT,
  email_verified: Boolean = WorkOS::OMIT,
  password: PasswordPlaintext | PasswordHashed = nil,
  phone_number: String = WorkOS::OMIT,
  profile_picture_url: String = WorkOS::OMIT,
  metadata: Hash{String => String} = WorkOS::OMIT,
  primary_auth_factor_id: String = WorkOS::OMIT,
  password_hash: String = nil,
  password_hash_type: String = nil,
  password_salt_position: String = nil,
  request_options: Hash = {}
) -> WorkOS::User
```

--------------------------------

### Create an SSO Connection

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/sso.md

Provision a new SAML or OAuth connection for an organization.

```ruby
client.sso.create_connection(
  organization_id: String,
  connection_type: String,
  name: String = nil,
  saml_metadata: String = nil,
  oauth_metadata: Hash = nil,
  request_options: Hash = {}
) -> WorkOS::Connection
```

```ruby
# Get IdP metadata XML from identity provider
saml_metadata = File.read("/path/to/idp_metadata.xml")

conn = WorkOS.client.sso.create_connection(
  organization_id: "org_123",
  connection_type: "SAML",
  name: "Okta",
  saml_metadata: saml_metadata
)

puts conn.id
puts conn.saml_idp_certificate_fingerprint
```

```ruby
oauth_config = {
  client_id: "google_client_id",
  client_secret: "google_client_secret"
}

conn = WorkOS.client.sso.create_connection(
  organization_id: "org_123",
  connection_type: "OAuth",
  name: "Google",
  oauth_metadata: oauth_config
)
```

--------------------------------

### Configure WorkOS singleton

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/client.md

Initialize the WorkOS client globally using the WorkOS.configure block, typically placed in a Rails initializer.

```ruby
# config/initializers/workos.rb
WorkOS.configure do |config|
  config.api_key = ENV.fetch("WORKOS_API_KEY")
  config.client_id = ENV["WORKOS_CLIENT_ID"]
  config.timeout = 120
end

# Elsewhere in your app
org = WorkOS.client.organizations.get_organization(id: "org_123")
```

--------------------------------

### Generate Admin Portal Link for Directory Sync

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/admin-portal.md

Creates a link for configuring directory synchronization services.

```ruby
link = WorkOS.client.admin_portal.generate_link(
  organization: org_id,
  intent: "dsync"
)
# User can set up directory synchronization
```

--------------------------------

### Initialize password variants

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/types.md

Choose between PasswordPlaintext and PasswordHashed based on whether the password is provided as raw text or a pre-computed hash.

```ruby
# Plaintext password (WorkOS hashes)
password = WorkOS::UserManagement::PasswordPlaintext.new(
  password: "user_password"
)

# Hashed password (you provide hash)
password = WorkOS::UserManagement::PasswordHashed.new(
  password_hash: "bcrypt_hash",
  password_hash_type: "bcrypt",
  password_salt_position: "suffix"
)
```

--------------------------------

### Use Public/PKCE Client

Source: https://github.com/workos/workos-ruby/blob/main/README.md

Generate authorization URLs for browser, mobile, or CLI applications using PKCE.

```ruby
public_client = WorkOS::PublicClient.create(client_id: "client_123")
url, verifier, state = public_client.user_management.get_authorization_url_with_pkce(
  provider: "authkit",
  redirect_uri: "https://example.com/callback"
)
```

--------------------------------

### Create a user with plaintext password

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/user-management.md

Initializes a new user record with a plaintext password and optional metadata.

```ruby
user = WorkOS.client.user_management.create_user(
  email: "alice@example.com",
  first_name: "Alice",
  last_name: "Smith",
  password: WorkOS::UserManagement::PasswordPlaintext.new(password: "TempPass123!"),
  metadata: {source: "invite_flow"}
)

puts "User created: #{user.id}"
```

--------------------------------

### Import users with pre-hashed passwords

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/user-management.md

Bulk imports users by providing existing password hashes and specifying the hashing algorithm and salt configuration.

```ruby
legacy_users = [
  {email: "user1@legacy.com", hash: "bcrypt_hash_1", salt_pos: "suffix"},
  {email: "user2@legacy.com", hash: "bcrypt_hash_2", salt_pos: "suffix"}
]

legacy_users.each do |u|
  WorkOS.client.user_management.create_user(
    email: u[:email],
    password: WorkOS::UserManagement::PasswordHashed.new(
      password_hash: u[:hash],
      password_hash_type: "bcrypt",
      password_salt_position: u[:salt_pos]
    )
  )
end
```

--------------------------------

### Configure Global WorkOS Client

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/client.md

Sets global configuration parameters such as API keys, timeouts, and logging preferences.

```ruby
WorkOS.configure do |config|
  config.api_key = ENV["WORKOS_API_KEY"]
  config.client_id = ENV["WORKOS_CLIENT_ID"]
  config.timeout = 60
  config.max_retries = 3
  config.logger = Logger.new($stdout)
  config.log_level = :info
end
```

--------------------------------

### List and Map Directory Users to WorkOS

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/directory-sync.md

Iterates through directory users and synchronizes them with WorkOS user management by creating or updating records based on email matching.

```ruby
directory_id = "dir_123"

# Get all directory users
dir_users = WorkOS.client.directory_sync.list_users(
  directory_id: directory_id,
  limit: 100
)

dir_users.auto_paging_each do |dir_user|
  # Check if user already exists in WorkOS
  begin
    workos_user = WorkOS.client.user_management.list_users(
      email: dir_user.email
    ).data.first

    if workos_user
      # Update existing user
      WorkOS.client.user_management.update_user(
        id: workos_user.id,
        first_name: dir_user.first_name,
        last_name: dir_user.last_name
      )
    else
      # Create new user
      WorkOS.client.user_management.create_user(
        email: dir_user.email,
        first_name: dir_user.first_name,
        last_name: dir_user.last_name
      )
    end
  rescue WorkOS::APIError => e
    Rails.logger.error "Failed to sync user #{dir_user.email}: #{e.message}"
  end
end
```

--------------------------------

### Configure VCR for WorkOS Tests

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/configuration.md

Set up VCR to record HTTP interactions and redact sensitive headers like Authorization.

```ruby
require "vcr"

VCR.configure do |config|
  config.cassette_library_dir = "spec/fixtures/cassettes"
  config.hook_into :webmock
  config.before_record do |interaction|
    # Redact API key from recordings
    interaction.request.headers.delete("Authorization")
  end
end

# In tests
describe "Organizations" do
  it "lists organizations" do
    VCR.use_cassette("organizations/list") do
      orgs = WorkOS.client.organizations.list_organizations
      expect(orgs.data).not_to be_empty
    end
  end
end
```

--------------------------------

### WorkOS.client.user_management.create_user

Source: https://github.com/workos/workos-ruby/blob/main/README.md

Creates a new user.

```APIDOC
## WorkOS.client.user_management.create_user

### Description
Creates a new user record within the WorkOS user management system.

### Parameters
- **email** (String) - Required - The email address of the user.
- **first_name** (String) - Optional - The first name of the user.
- **last_name** (String) - Optional - The last name of the user.
```

--------------------------------

### create_organization

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/organizations.md

Create a new organization.

```APIDOC
## create_organization

### Description
Create a new organization.

### Parameters
- **name** (String) - Required - Organization name
- **allow_profiles_outside_organization** (Boolean) - Optional - Allow SSO sign-in from profiles outside org domain
- **domains** (Array<String>) - Optional - Deprecated; use domain_data instead
- **domain_data** (Array<WorkOS::OrganizationDomainData>) - Optional - Domains with verification state
- **metadata** (Hash) - Optional - Custom key-value metadata
- **external_id** (String) - Optional - Your internal identifier for this organization
- **request_options** (Hash) - Optional - Per-call HTTP options

### Returns
WorkOS::Organization object with assigned id.
```

--------------------------------

### Configure Session Manager with Sealed Cookies

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/configuration.md

Initializes the session manager using a 32-byte password for encryption and demonstrates sealing and unsealing session data.

```ruby
require "securerandom"

# Generate a 32-byte password (one time, store securely)
cookie_password = SecureRandom.base64(32)

# Configure session manager
session_manager = WorkOS.client.session_manager(
  encryptor: CustomEncryptor.new(cookie_password)
)

# Seal session
sealed = session_manager.seal_session(
  user_id: "user_123",
  organization_id: "org_456",
  access_token: "access_token_value"
)

# Unseal session
unsealed = session_manager.unseal_session(sealed)
```

--------------------------------

### Handle WorkOS::NotFoundError

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/errors.md

Catch 404 errors when a requested resource does not exist.

```ruby
begin
  WorkOS.client.organizations.get_organization(id: "org_nonexistent")
rescue WorkOS::NotFoundError => e
  puts "Organization not found: #{e.message}"
  puts "Check the organization ID: #{e.code}"
end
```

--------------------------------

### Configure Request Timeouts

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/configuration.md

Demonstrates setting a global timeout via configuration or overriding it for specific API requests.

```ruby
# Global timeout
WorkOS.configure do |config|
  config.timeout = 120  # 120 seconds
end

# Per-request override
org = WorkOS.client.organizations.get_organization(
  id: "org_123",
  request_options: {timeout: 60}
)
```

--------------------------------

### Generate Admin Portal Link for Domain Verification

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/admin-portal.md

Creates a link for verifying organization domains via DNS.

```ruby
link = WorkOS.client.admin_portal.generate_link(
  organization: org_id,
  intent: "domain_verification"
)
# User can add and verify domains
```

--------------------------------

### Configure Global Logging

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/configuration.md

Set up global logging for the WorkOS module to assist with debugging.

```ruby
require "logger"

WorkOS.configure do |config|
  config.api_key = ENV.fetch("WORKOS_API_KEY")
  config.logger = Logger.new($stdout)
  config.log_level = :debug
end
```

--------------------------------

### create_connection

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/sso.md

Create a new SSO connection for an organization.

```APIDOC
## create_connection

### Description
Create a new SSO connection.

### Method
Ruby SDK Method

### Parameters
- **organization_id** (String) - Required - Organization ID
- **connection_type** (String) - Required - Type: "SAML" or "OAuth"
- **name** (String) - Optional - Display name for connection
- **saml_metadata** (String) - Optional - SAML IdP metadata XML (for SAML type)
- **oauth_metadata** (Hash) - Optional - OAuth provider configuration (for OAuth type)
- **request_options** (Hash) - Optional - Per-call HTTP options

### Returns
WorkOS::Connection object with provisioned settings.

### Throws
WorkOS::InvalidRequestError on invalid metadata or duplicate connection.
```

--------------------------------

### Initialize resource target variants

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/types.md

Select the appropriate target class based on whether the resource is identified by its internal ID or an external ID.

```ruby
# Target by ID
target = WorkOS::Authorization::ResourceTargetById.new(
  resource_id: "res_123"
)

# Target by external ID
target = WorkOS::Authorization::ResourceTargetByExternalId.new(
  resource_external_id: "ext_456",
  resource_type_slug: "workspace"
)
```

--------------------------------

### Generate Admin Portal Link for SSO

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/admin-portal.md

Creates a link for configuring SSO connections such as SAML, OAuth, or OIDC.

```ruby
link = WorkOS.client.admin_portal.generate_link(
  organization: org_id,
  intent: "sso",
  return_url: "https://app.example.com/settings"
)
# User can create SAML or OAuth connections
```

--------------------------------

### Regenerate Ruby SDK

Source: https://github.com/workos/workos-ruby/blob/main/AGENTS.md

Command to trigger the SDK generation process from the openapi-spec repository.

```bash
npm run sdk:generate -- --lang ruby --output workos-ruby
```

--------------------------------

### Generate Admin Portal Link for Log Streams

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/admin-portal.md

Creates a link for configuring log stream destinations like Datadog or Splunk.

```ruby
link = WorkOS.client.admin_portal.generate_link(
  organization: org_id,
  intent: "log_streams"
)
# User can set up log streaming
```

--------------------------------

### Test with VCR

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/README.md

Use VCR to record and replay HTTP interactions during test execution.

```ruby
describe "Organizations" do
  it "lists organizations" do
    VCR.use_cassette("organizations/list") do
      orgs = WorkOS.client.organizations.list_organizations
      expect(orgs.data).not_to be_empty
    end
  end
end
```

--------------------------------

### WorkOS.client.webhooks.construct_event

Source: https://github.com/workos/workos-ruby/blob/main/README.md

Verifies and constructs a webhook event.

```APIDOC
## WorkOS.client.webhooks.construct_event

### Description
Verifies the signature of an incoming webhook request and constructs the event object.

### Parameters
- **payload** (String) - Required - The raw request body.
- **sig_header** (String) - Required - The signature header from the request.
- **secret** (String) - Required - The webhook secret used for verification.
```

--------------------------------

### Configure Sidekiq Middleware

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/configuration.md

Use middleware to manage client lifecycle in Sidekiq workers.

```yaml
# config/sidekiq.yml
:server_middleware:
  - !ruby/object:Sidekiq::Middleware::Server::WorkOSConnectionPooling
    on_start: ->() { WorkOS.reset_client }
    on_shutdown: ->() { WorkOS.client&.shutdown }
```

--------------------------------

### Retrieve Current Configuration

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/configuration.md

Accesses the current global configuration object to inspect settings.

```ruby
config = WorkOS.configuration
puts config.api_key
puts config.client_id
puts config.timeout
```

--------------------------------

### List Users with Pagination

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/user-management.md

Defines the method signature and usage for listing users with optional filtering and auto-paging.

```ruby
client.user_management.list_users(
  organization_id: String = nil,
  before: String = nil,
  after: String = nil,
  limit: Integer = 10,
  order: String = "desc",
  email: String = nil,
  request_options: Hash = {}
) -> WorkOS::Types::ListStruct<WorkOS::User>
```

```ruby
users = WorkOS.client.user_management.list_users(limit: 100, organization_id: "org_123")

users.auto_paging_each do |user|
  puts "#{user.email}: #{user.first_name} #{user.last_name}"
end
```

--------------------------------

### Generate Admin Portal Link for Audit Logs

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/admin-portal.md

Creates a link for managing audit log settings and retention policies.

```ruby
link = WorkOS.client.admin_portal.generate_link(
  organization: org_id,
  intent: "audit_logs"
)
# User can view audit events and configure retention
```

--------------------------------

### WorkOS.reset_client

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/client.md

Resets the global client instance.

```APIDOC
## WorkOS.reset_client

### Description
Clears the singleton client cache and shuts down existing connections. Useful after reconfiguring the SDK or when forking processes.
```

--------------------------------

### Create Organization

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/organizations.md

Create a new organization with specified domains and metadata. Throws WorkOS::APIError on invalid input or duplicate external_id.

```ruby
org = WorkOS.client.organizations.create_organization(
  name: "Acme Corp",
  domain_data: [
    {domain: "acme.com", verification_state: "pending"}
  ],
  metadata: {"account_tier" => "enterprise"},
  external_id: "tenant_acme_123"
)

puts org.id  # => "org_..."
puts org.domains  # => ["acme.com"]
```

--------------------------------

### Generate Admin Portal Link for Certificate Renewal

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/admin-portal.md

Creates a link for managing and renewing SAML signing certificates.

```ruby
link = WorkOS.client.admin_portal.generate_link(
  organization: org_id,
  intent: "certificate_renewal"
)
# User can manage SAML certificates
```

--------------------------------

### Handle API and connection errors

Source: https://github.com/workos/workos-ruby/blob/main/README.md

Demonstrates rescuing specific WorkOS error types to handle API failures and connection issues.

```ruby
begin
  WorkOS.client.organizations.get_organization(id: "org_123")
rescue WorkOS::APIError => e
  warn "#{e.class}: #{e.message}"
  warn "status=#{e.http_status} request_id=#{e.request_id} code=#{e.code}"
rescue WorkOS::APIConnectionError => e
  warn "connection failure: #{e.message}"
end
```

--------------------------------

### list_connections

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/sso.md

List all SSO connections with optional filtering parameters.

```APIDOC
## list_connections

### Description
List all SSO connections with optional filtering.

### Method
Ruby SDK Method

### Parameters
- **before** (String) - Optional - Cursor for reverse pagination
- **after** (String) - Optional - Cursor for forward pagination
- **limit** (Integer) - Optional - Results per page (1-100)
- **order** (String) - Optional - Sort order: "asc" or "desc"
- **connection_type** (String) - Optional - Filter by type: "SAML", "OAuth", "OIDC"
- **domain** (String) - Optional - Filter by organization domain
- **organization_id** (String) - Optional - Filter by organization ID
- **search** (String) - Optional - Search by connection name
- **request_options** (Hash) - Optional - Per-call HTTP options

### Returns
WorkOS::Types::ListStruct<WorkOS::Connection>
```

--------------------------------

### Initialize PasswordHashed

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/user-management.md

Used for migrating existing users with pre-hashed passwords.

```ruby
WorkOS::UserManagement::PasswordHashed.new(
  password_hash: String,
  password_hash_type: String,
  password_salt_position: String = nil
)
```

--------------------------------

### Enroll user with TOTP

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/multi-factor-auth.md

Enrolls a TOTP factor, displays the QR code or secret to the user, and verifies the provided code.

```ruby
# 1. Enroll TOTP factor
factor = WorkOS.client.multi_factor_auth.enroll_factor(
  type: "totp",
  totp_issuer: "MyApp",
  totp_user: current_user.email,
  user_id: current_user.id
)

# 2. Display QR code to user
# In view:
# <%= image_tag("data:image/png;base64,#{factor.totp_qr_code}") %>
# Manual entry: <%= factor.totp_secret %>

# 3. Have user scan and confirm with code
session[:pending_factor_id] = factor.id

# 4. In verification endpoint:
code = params[:totp_code]
challenge = WorkOS.client.multi_factor_auth.verify_challenge(
  id: session[:pending_factor_id],
  code: code
)

if challenge.valid
  # Factor confirmed
  session.delete(:pending_factor_id)
  flash[:success] = "TOTP factor enabled"
end
```

--------------------------------

### List Directory Users

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/directory-sync.md

Retrieves a paginated list of users synced from a directory.

```ruby
client.directory_sync.list_users(
  directory_id: String,
  before: String = nil,
  after: String = nil,
  limit: Integer = 10,
  order: String = "desc",
  request_options: Hash = {}
) -> WorkOS::Types::ListStruct<WorkOS::DirectoryUser>
```

```ruby
users = WorkOS.client.directory_sync.list_users(
  directory_id: "dir_123",
  limit: 100
)

users.auto_paging_each do |user|
  puts "#{user.email} - #{user.state}"
end
```

--------------------------------

### Reset WorkOS Client

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/configuration.md

Clear the singleton client instance to force a fresh initialization after configuration changes.

```ruby
# Reset after configuration change
WorkOS.configuration.api_key = new_key
WorkOS.reset_client

# Next call to WorkOS.client creates fresh instance
org = WorkOS.client.organizations.list_organizations
```

--------------------------------

### Authenticate user and handle MFA

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/user-management.md

Authenticates a user via password grant and checks for an authentication challenge to trigger MFA.

```ruby
begin
  response = WorkOS.client.user_management.create_authenticate(
    client_id: ENV["WORKOS_CLIENT_ID"],
    grant_type: "password",
    client_secret: ENV["WORKOS_CLIENT_SECRET"],
    email: params[:email],
    password: params[:password]
  )

  if response.authentication_challenge
    # Store challenge ID in session; prompt for MFA code
    session[:auth_challenge_id] = response.authentication_challenge.id
    render :mfa_required
  else
    # Complete authentication
    session[:access_token] = response.access_token
    session[:user_id] = response.user.id
    redirect_to dashboard_path
  end
rescue WorkOS::InvalidRequestError => e
  flash.now[:error] = "Invalid credentials"
  render :login
end
```

--------------------------------

### Handle Link Expiration

Source: https://github.com/workos/workos-ruby/blob/main/_autodocs/api-reference/admin-portal.md

Ensures fresh links are generated for the Admin Portal, as they expire after 24 hours.

```ruby
def get_admin_portal_link(org_id, intent)
  # Always generate fresh link (no caching recommended)
  response = WorkOS.client.admin_portal.generate_link(
    organization: org_id,
    intent: intent
  )
  response.link
end

# In controller
def show_admin_panel
  @sso_link = get_admin_portal_link(current_org.id, "sso")
  @dsync_link = get_admin_portal_link(current_org.id, "dsync")
end
```
Tokens:
Raw