Module: WorkOS::UserManagement

Extended by:
Client, Deprecation
Defined in:
lib/workos/user_management.rb

Overview

rubocop:disable Metrics/ModuleLength

Defined Under Namespace

Modules: Types

Constant Summary collapse

PROVIDERS = 
WorkOS::UserManagement::Types::Provider::ALL
AUTH_FACTOR_TYPES = 
WorkOS::UserManagement::Types::AuthFactorType::ALL

Class Method Summary collapse

Methods included from Client

client, delete_request, execute_request, get_request, handle_error_response, post_request, put_request, user_agent

Methods included from Deprecation

warn_deprecation

Class Method Details

.authenticate_with_code(code:, client_id:, ip_address: nil, user_agent: nil, session: nil) ⇒ Object

Authenticate a user using OAuth or an organization’s SSO connection.

query parameter in the callback to the Redirect URI. the optional cookie password.

Parameters:

  • code (String) —

    The authorization value which was passed back as a

  • client_id (String) —

    The WorkOS client ID for the environment

  • ip_address (String) (defaults to: nil) —

    The IP address of the request from the user who is attempting to authenticate.

  • user_agent (String) (defaults to: nil) —

    The user agent of the request from the user who is attempting to authenticate.

  • session (Hash) (defaults to: nil) —

    An optional hash that determines whether the session should be sealed and

Returns:

  • WorkOS::AuthenticationResponse



312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
 
# File 'lib/workos/user_management.rb', line 312

def authenticate_with_code(
  code:,
  client_id:,
  ip_address: nil,
  user_agent: nil,
  session: nil
)
  if session && (session[:seal_session] == true) && session[:cookie_password].nil?
    raise ArgumentError, 'cookie_password is required when sealing session'
  end

  response = execute_request(
    request: post_request(
      path: '/user_management/authenticate',
      body: {
        code: code,
        client_id: client_id,
        client_secret: WorkOS.config.key!,
        ip_address: ip_address,
        user_agent: user_agent,
        grant_type: 'authorization_code',
      },
    ),
  )

  WorkOS::AuthenticationResponse.new(response.body, session)
end

.authenticate_with_email_verification(code:, client_id:, pending_authentication_token:, ip_address: nil, user_agent: nil) ⇒ Object

Authenticate a user using Email Verification Code.

authentication attempt due to an unverified email address.

Parameters:

  • code (String) —

    The one-time code that was emailed to the user.

  • client_id (String) —

    The WorkOS client ID for the environment

  • pending_authentication_token (String) —

    The token returned from a failed email/password or OAuth

  • ip_address (String) (defaults to: nil) —

    The IP address of the request from the user who is attempting to authenticate.

  • user_agent (String) (defaults to: nil) —

    The user agent of the request from the user who is attempting to authenticate.

Returns:

  • WorkOS::AuthenticationResponse



502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
 
# File 'lib/workos/user_management.rb', line 502

def authenticate_with_email_verification(
  code:,
  client_id:,
  pending_authentication_token:,
  ip_address: nil,
  user_agent: nil
)
  response = execute_request(
    request: post_request(
      path: '/user_management/authenticate',
      body: {
        code: code,
        client_id: client_id,
        pending_authentication_token: pending_authentication_token,
        client_secret: WorkOS.config.key!,
        grant_type: 'urn:workos:oauth:grant-type:email-verification:code',
        ip_address: ip_address,
        user_agent: user_agent,
      },
    ),
  )

  WorkOS::AuthenticationResponse.new(response.body)
end

.authenticate_with_magic_auth(code:, email:, client_id:, ip_address: nil, user_agent: nil, link_authorization_code: nil) ⇒ Object

Authenticate user by Magic Auth Code.

after having completed a Magic Code challenge.

Parameters:

  • code (String) —

    The one-time code that was emailed to the user.

  • email (String) —

    The email address of the user.

  • client_id (String) —

    The WorkOS client ID for the environment.

  • ip_address (String) (defaults to: nil) —

    The IP address of the request from the user who is attempting to authenticate.

  • link_authorization_code (String) (defaults to: nil) —

    Used to link an OAuth profile to an existing user,

  • user_agent (String) (defaults to: nil) —

    The user agent of the request from the user who is attempting to authenticate.

Returns:

  • WorkOS::AuthenticationResponse



392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
 
# File 'lib/workos/user_management.rb', line 392

def authenticate_with_magic_auth(
  code:,
  email:,
  client_id:,
  ip_address: nil,
  user_agent: nil,
  link_authorization_code: nil
)
  response = execute_request(
    request: post_request(
      path: '/user_management/authenticate',
      body: {
        code: code,
        email: email,
        client_id: client_id,
        client_secret: WorkOS.config.key!,
        ip_address: ip_address,
        user_agent: user_agent,
        grant_type: 'urn:workos:oauth:grant-type:magic-auth:code',
        link_authorization_code: link_authorization_code,
      },
    ),
  )

  WorkOS::AuthenticationResponse.new(response.body)
end

.authenticate_with_organization_selection(client_id:, organization_id:, pending_authentication_token:, ip_address: nil, user_agent: nil) ⇒ Object

Authenticate a user into an organization they are a member of.

Parameters:

  • client_id (String) —

    The WorkOS client ID for the environment.

  • organization_id (String) —

    The organization ID the user selected to sign in to.

  • pending_authentication_token (String) —

    The pending authentication token

  • ip_address (String) (defaults to: nil) —

    The IP address of the request from the user who is attempting to authenticate.

  • user_agent (String) (defaults to: nil) —

    The user agent of the request from the user who is attempting to authenticate.

Returns:

  • WorkOS::AuthenticationResponse



428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
 
# File 'lib/workos/user_management.rb', line 428

def authenticate_with_organization_selection(
  client_id:,
  organization_id:,
  pending_authentication_token:,
  ip_address: nil,
  user_agent: nil
)
  response = execute_request(
    request: post_request(
      path: '/user_management/authenticate',
      body: {
        client_id: client_id,
        client_secret: WorkOS.config.key!,
        ip_address: ip_address,
        user_agent: user_agent,
        grant_type: 'urn:workos:oauth:grant-type:organization-selection',
        organization_id: organization_id,
        pending_authentication_token: pending_authentication_token,
      },
    ),
  )

  WorkOS::AuthenticationResponse.new(response.body)
end

.authenticate_with_password(email:, password:, client_id:, ip_address: nil, user_agent: nil) ⇒ Object

Authenticates user by email and password.

Parameters:

  • email (String) —

    The email address of the user.

  • password (String) —

    The password for the user.

  • client_id (String) —

    The WorkOS client ID for the environment

  • ip_address (String) (defaults to: nil) —

    The IP address of the request from the user who is attempting to authenticate.

  • user_agent (String) (defaults to: nil) —

    The user agent of the request from the user who is attempting to authenticate.

Returns:

  • WorkOS::AuthenticationResponse



282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
 
# File 'lib/workos/user_management.rb', line 282

def authenticate_with_password(email:, password:, client_id:, ip_address: nil, user_agent: nil)
  response = execute_request(
    request: post_request(
      path: '/user_management/authenticate',
      body: {
        client_id: client_id,
        client_secret: WorkOS.config.key!,
        email: email,
        password: password,
        ip_address: ip_address,
        user_agent: user_agent,
        grant_type: 'password',
      },
    ),
  )

  WorkOS::AuthenticationResponse.new(response.body)
end

.authenticate_with_refresh_token(refresh_token:, client_id:, organization_id: nil, ip_address: nil, user_agent: nil, session: nil) ⇒ Object

Authenticate a user using a refresh token.

the optional cookie password.

Parameters:

  • refresh_token (String) —

    The refresh token previously obtained from a successful authentication call

  • client_id (String) —

    The WorkOS client ID for the environment

  • organization_id (String) (defaults to: nil) —

    The organization to issue the new access token for. (Optional)

  • ip_address (String) (defaults to: nil) —

    The IP address of the request from the user who is attempting to authenticate.

  • user_agent (String) (defaults to: nil) —

    The user agent of the request from the user who is attempting to authenticate.

  • session (Hash) (defaults to: nil) —

    An optional hash that determines whether the session should be sealed and

Returns:

  • WorkOS::RefreshAuthenticationResponse



351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
 
# File 'lib/workos/user_management.rb', line 351

def authenticate_with_refresh_token(
  refresh_token:,
  client_id:,
  organization_id: nil,
  ip_address: nil,
  user_agent: nil,
  session: nil
)
  if session && (session[:seal_session] == true) && session[:cookie_password].nil?
    raise ArgumentError, 'cookie_password is required when sealing session'
  end

  response = execute_request(
    request: post_request(
      path: '/user_management/authenticate',
      body: {
        refresh_token: refresh_token,
        client_id: client_id,
        client_secret: WorkOS.config.key!,
        ip_address: ip_address,
        user_agent: user_agent,
        grant_type: 'refresh_token',
        organization_id: organization_id,
      },
    ),
  )

  WorkOS::RefreshAuthenticationResponse.new(response.body, session)
end

.authenticate_with_totp(code:, client_id:, pending_authentication_token:, authentication_challenge_id:, ip_address: nil, user_agent: nil) ⇒ Object

Authenticate a user using TOTP.

from the initial authentication request. authentication request.

Parameters:

  • code (String) —

    The one-time code that was emailed to the user.

  • client_id (String) —

    The WorkOS client ID for the environment

  • pending_authentication_token (String) —

    The pending authentication token

  • authentication_challenge_id (String) —

    The authentication challenge ID for the

  • ip_address (String) (defaults to: nil) —

    The IP address of the request from the user who is attempting to authenticate.

  • user_agent (String) (defaults to: nil) —

    The user agent of the request from the user who is attempting to authenticate.

Returns:

  • WorkOS::AuthenticationResponse



465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
 
# File 'lib/workos/user_management.rb', line 465

def authenticate_with_totp(
  code:,
  client_id:,
  pending_authentication_token:,
  authentication_challenge_id:,
  ip_address: nil,
  user_agent: nil
)
  response = execute_request(
    request: post_request(
      path: '/user_management/authenticate',
      body: {
        code: code,
        client_id: client_id,
        client_secret: WorkOS.config.key!,
        pending_authentication_token: pending_authentication_token,
        grant_type: 'urn:workos:oauth:grant-type:mfa-totp',
        authentication_challenge_id: authentication_challenge_id,
        ip_address: ip_address,
        user_agent: user_agent,
      },
    ),
  )

  WorkOS::AuthenticationResponse.new(response.body)
end

.authorization_url(redirect_uri:, client_id: nil, domain_hint: nil, login_hint: nil, provider: nil, connection_id: nil, organization_id: nil, state: '') ⇒ String

Generate an OAuth 2.0 authorization URL that automatically directs a user to their Identity Provider.

OAuth-compatible provider. Only ‘authkit’, ‘AppleOAuth’, ‘GitHubOAuth’, ‘GoogleOAuth’, and ‘MicrosoftOAuth’ are supported. initiate SSO for an Organization. field of the IdP sign-in page for the user, if you know their username ahead of time. initiating authentication with Microsoft OAuth, or with a GoogleSAML connection type. rubocop:disable Metrics/ParameterLists

Examples:

WorkOS::UserManagement.authorization_url(
  connection_id: 'conn_123',
  client_id: 'project_01DG5TGK363GRVXP3ZS40WNGEZ',
  redirect_uri: 'https://your-app.com/callback',
  state: {
    next_page: '/docs'
  }.to_s
)

=> "https://api.workos.com/user_management/authorize?connection_id=conn_123" \
   "&client_id=project_01DG5TGK363GRVXP3ZS40WNGEZ" \
   "&redirect_uri=https%3A%2F%2Fyour-app.com%2Fcallback&" \
   "response_type=code&state=%7B%3Anext_page%3D%3E%22%2Fdocs%22%7D"

Parameters:

  • redirect_uri (String) —

    The URI where users are directed after completing the authentication step. Must match a configured redirect URI on your WorkOS dashboard.

  • client_id (String) (defaults to: nil) —

    This value can be obtained from the API Keys page in the WorkOS dashboard.

  • provider (String) (defaults to: nil) —

    A provider name is used to initiate SSO using an

  • connection_id (String) (defaults to: nil) —

    The ID for a Connection configured on WorkOS.

  • organization_id (String) (defaults to: nil) —

    The organization_id selector is used to

  • state (String) (defaults to: '') —

    An arbitrary state object that is preserved and available to the client in the response.

  • login_hint (String) (defaults to: nil) —

    Can be used to pre-fill the username/email address

  • domain_hint (String) (defaults to: nil) —

    Can be used to pre-fill the domain field when

Returns:

  • (String) 


93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/workos/user_management.rb', line 93

def authorization_url(
  redirect_uri:,
  client_id: nil,
  domain_hint: nil,
  login_hint: nil,
  provider: nil,
  connection_id: nil,
  organization_id: nil,
  state: ''
)

  validate_authorization_url_arguments(
    provider: provider,
    connection_id: connection_id,
    organization_id: organization_id,
  )

  query = URI.encode_www_form({
    client_id: client_id,
    redirect_uri: redirect_uri,
    response_type: 'code',
    state: state,
    domain_hint: domain_hint,
    login_hint: ,
    provider: provider,
    connection_id: connection_id,
    organization_id: organization_id,
  }.compact)

  "https://#{WorkOS.config.api_hostname}/user_management/authorize?#{query}"
end

.create_magic_auth(email:, invitation_token: nil) ⇒ Object

Creates a MagicAuth code

Parameters:

  • email (String) —

    The email address of the recipient.

  • invitation_token (String) (defaults to: nil) —

    The token of an Invitation, if required.

Returns:

  • WorkOS::MagicAuth



601
602
603
604
605
606
607
608
609
610
611
612
613
614
 
# File 'lib/workos/user_management.rb', line 601

def create_magic_auth(email:, invitation_token: nil)
  response = execute_request(
    request: post_request(
      path: '/user_management/magic_auth',
      body: {
        email: email,
        invitation_token: invitation_token,
      },
      auth: true,
    ),
  )

  WorkOS::MagicAuth.new(response.body)
end

.create_organization_membership(user_id:, organization_id:, role_slug: nil) ⇒ WorkOS::OrganizationMembership

Create an Organization Membership

Parameters:

  • user_id (String) —

    The ID of the User.

  • organization_id (String) —

    The ID of the Organization to which the user belongs to.

  • role_slug (String) (defaults to: nil) —

    The slug of the role to grant to this membership. (Optional)

Returns:



886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
 
# File 'lib/workos/user_management.rb', line 886

def create_organization_membership(user_id:, organization_id:, role_slug: nil)
  request = post_request(
    path: '/user_management/organization_memberships',
    body: {
      user_id: user_id,
      organization_id: organization_id,
      role_slug: role_slug,
    },
    auth: true,
  )

  response = execute_request(request: request)

  WorkOS::OrganizationMembership.new(response.body)
end

.create_password_reset(email:) ⇒ Object

Creates a password reset token

Parameters:

  • email (String) —

    The email address of the user.

Returns:

  • WorkOS::PasswordReset



768
769
770
771
772
773
774
775
776
777
778
779
780
 
# File 'lib/workos/user_management.rb', line 768

def create_password_reset(email:)
  response = execute_request(
    request: post_request(
      path: '/user_management/password_reset',
      body: {
        email: email,
      },
      auth: true,
    ),
  )

  WorkOS::PasswordReset.new(response.body)
end

.create_user(email:, password: nil, first_name: nil, last_name: nil, email_verified: nil, password_hash: nil, password_hash_type: nil) ⇒ WorkOS::User

Create a user

rubocop:disable Metrics/ParameterLists

Parameters:

  • email (String) —

    The email address of the user.

  • password (String) (defaults to: nil) —

    The password to set for the user.

  • first_name (String) (defaults to: nil) —

    The user’s first name.

  • last_name (String) (defaults to: nil) —

    The user’s last name.

  • email_verified (Boolean) (defaults to: nil) —

    Whether the user’s email address was previously verified.

  • password_hash (String) (defaults to: nil) —

    The user’s hashed password.

  • [String] (Hash) —

    a customizable set of options

Returns:



189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
 
# File 'lib/workos/user_management.rb', line 189

def create_user(
  email:,
  password: nil,
  first_name: nil,
  last_name: nil,
  email_verified: nil,
  password_hash: nil,
  password_hash_type: nil
)
  request = post_request(
    path: '/user_management/users',
    body: {
      email: email,
      password: password,
      first_name: first_name,
      last_name: last_name,
      email_verified: email_verified,
      password_hash: password_hash,
      password_hash_type: password_hash_type,
    },
    auth: true,
  )

  response = execute_request(request: request)

  WorkOS::User.new(response.body)
end

.deactivate_organization_membership(id:) ⇒ Object

Deactivate an Organization Membership

Parameters:

  • id (String) —

    The unique ID of the Organization Membership.

Returns:

  • WorkOS::OrganizationMembership



944
945
946
947
948
949
950
951
952
953
 
# File 'lib/workos/user_management.rb', line 944

def deactivate_organization_membership(id:)
  response = execute_request(
    request: put_request(
      path: "/user_management/organization_memberships/#{id}/deactivate",
      auth: true,
    ),
  )

  WorkOS::OrganizationMembership.new(response.body)
end

.delete_organization_membership(id:) ⇒ Bool

Delete an Organization Membership

Parameters:

  • id (String) —

    The unique ID of the Organization Membership.

Returns:

  • (Bool) —

    • returns ‘true` if successful



928
929
930
931
932
933
934
935
936
937
 
# File 'lib/workos/user_management.rb', line 928

def delete_organization_membership(id:)
  response = execute_request(
    request: delete_request(
      path: "/user_management/organization_memberships/#{id}",
      auth: true,
    ),
  )

  response.is_a? Net::HTTPSuccess
end

.delete_user(id:) ⇒ Bool

Delete a User

Parameters:

  • id (String) —

    The unique ID of the User.

Returns:

  • (Bool) —

    • returns ‘true` if successful



262
263
264
265
266
267
268
269
270
271
 
# File 'lib/workos/user_management.rb', line 262

def delete_user(id:)
  response = execute_request(
    request: delete_request(
      path: "/user_management/users/#{id}",
      auth: true,
    ),
  )

  response.is_a? Net::HTTPSuccess
end

.enroll_auth_factor(user_id:, type:, totp_issuer: nil, totp_user: nil, totp_secret: nil) ⇒ Object

Enroll a user into an authentication factor.

factor. Generated if not provided. (Optional)

Parameters:

  • user_id (String) —

    The id for the user.

  • type (String) —

    The type of the factor to enroll. Only option available is totp.

  • totp_issuer (String) (defaults to: nil) —

    For totp factors. Typically your application or company name, this helps users distinguish between factors in authenticator apps.

  • totp_user (String) (defaults to: nil) —

    For totp factors. Used as the account name in authenticator apps.

  • totp_secret (String) (defaults to: nil) —

    For totp factors. The Base32 encdoded secret key for the

Returns:

  • WorkOS::AuthenticationFactorAndChallenge



649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
 
# File 'lib/workos/user_management.rb', line 649

def enroll_auth_factor(user_id:, type:, totp_issuer: nil, totp_user: nil, totp_secret: nil)
  validate_auth_factor_type(
    type: type,
  )

  response = execute_request(
    request: post_request(
      path: "/user_management/users/#{user_id}/auth_factors",
      body: {
        type: type,
        totp_issuer: totp_issuer,
        totp_user: totp_user,
        totp_secret: totp_secret,
      },
      auth: true,
    ),
  )

  WorkOS::AuthenticationFactorAndChallenge.new(response.body)
end

.find_invitation_by_token(token:) ⇒ Object

Finds an Invitation by Token

Parameters:

  • token (String) —

    The token of the Invitation.

Returns:

  • WorkOS::Invitation



992
993
994
995
996
997
998
999
1000
1001
 
# File 'lib/workos/user_management.rb', line 992

def find_invitation_by_token(token:)
  response = execute_request(
    request: get_request(
      path: "/user_management/invitations/by_token/#{token}",
      auth: true,
    ),
  )

  WorkOS::Invitation.new(response.body)
end

.get_email_verification(id:) ⇒ Object

Gets an email verification object

Parameters:

  • id (String) —

    The unique ID of the EmailVerification object.

Returns:

  • WorkOS::EmailVerification



700
701
702
703
704
705
706
707
708
709
 
# File 'lib/workos/user_management.rb', line 700

def get_email_verification(id:)
  response = execute_request(
    request: get_request(
      path: "/user_management/email_verification/#{id}",
      auth: true,
    ),
  )

  WorkOS::EmailVerification.new(response.body)
end

.get_invitation(id:) ⇒ Object

Gets an Invitation

Parameters:

  • id (String) —

    The unique ID of the Invitation.

Returns:

  • WorkOS::Invitation



976
977
978
979
980
981
982
983
984
985
 
# File 'lib/workos/user_management.rb', line 976

def get_invitation(id:)
  response = execute_request(
    request: get_request(
      path: "/user_management/invitations/#{id}",
      auth: true,
    ),
  )

  WorkOS::Invitation.new(response.body)
end

.get_jwks_url(client_id) ⇒ Object

Get the JWKS URL

The JWKS can be used to validate the access token returned upon successful authentication

Parameters:

  • client_id (String) —

    The WorkOS client ID for the environment

Returns:

  • String



572
573
574
575
576
577
 
# File 'lib/workos/user_management.rb', line 572

def get_jwks_url(client_id)
  URI::HTTPS.build(
    host: WorkOS.config.api_hostname,
    path: "/sso/jwks/#{client_id}",
  ).to_s
end

.get_logout_url(session_id:, return_to: nil) ⇒ Object

Get the logout URL for a session

The user’s browser should be navigated to this URL

Parameters:

  • session_id (String) —

    The session ID can be found in the ‘sid` claim of the access token

  • return_to (String) (defaults to: nil) —

    The URL to redirect the user to after logging out

Returns:

  • String



536
537
538
539
540
541
542
543
544
545
 
# File 'lib/workos/user_management.rb', line 536

def get_logout_url(session_id:, return_to: nil)
  params = { session_id: session_id }
  params[:return_to] = return_to if return_to

  URI::HTTPS.build(
    host: WorkOS.config.api_hostname,
    path: '/user_management/sessions/logout',
    query: URI.encode_www_form(params),
  ).to_s
end

.get_magic_auth(id:) ⇒ Object

Gets a Magic Auth object

Parameters:

  • id (String) —

    The unique ID of the MagicAuth object.

Returns:

  • WorkOS::MagicAuth



584
585
586
587
588
589
590
591
592
593
 
# File 'lib/workos/user_management.rb', line 584

def get_magic_auth(id:)
  response = execute_request(
    request: get_request(
      path: "/user_management/magic_auth/#{id}",
      auth: true,
    ),
  )

  WorkOS::MagicAuth.new(response.body)
end

.get_organization_membership(id:) ⇒ Object

Get an Organization Membership

Parameters:

  • id (String) —

    The unique ID of the Organization Membership.

Returns:

  • WorkOS::OrganizationMembership



832
833
834
835
836
837
838
839
840
841
 
# File 'lib/workos/user_management.rb', line 832

def get_organization_membership(id:)
  response = execute_request(
    request: get_request(
      path: "/user_management/organization_memberships/#{id}",
      auth: true,
    ),
  )

  WorkOS::OrganizationMembership.new(response.body)
end

.get_password_reset(id:) ⇒ Object

Gets a password reset object

Parameters:

  • id (String) —

    The unique ID of the PasswordReset object.

Returns:

  • WorkOS::PasswordReset



752
753
754
755
756
757
758
759
760
761
 
# File 'lib/workos/user_management.rb', line 752

def get_password_reset(id:)
  response = execute_request(
    request: get_request(
      path: "/user_management/password_reset/#{id}",
      auth: true,
    ),
  )

  WorkOS::PasswordReset.new(response.body)
end

.get_user(id:) ⇒ Object

Get a User

Parameters:

  • id (String) —

    The unique ID of the User.

Returns:

  • WorkOS::User



131
132
133
134
135
136
137
138
139
140
 
# File 'lib/workos/user_management.rb', line 131

def get_user(id:)
  response = execute_request(
    request: get_request(
      path: "/user_management/users/#{id}",
      auth: true,
    ),
  )

  WorkOS::User.new(response.body)
end

.list_auth_factors(user_id:) ⇒ Object

Get all auth factors for a user

Parameters:

  • user_id (String) —

    The id for the user.

Returns:

  • WorkOS::ListStruct



675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
 
# File 'lib/workos/user_management.rb', line 675

def list_auth_factors(user_id:)
  response = execute_request(
    request: get_request(
      path: "/user_management/users/#{user_id}/auth_factors",
      auth: true,
    ),
  )

  parsed_response = JSON.parse(response.body)

  auth_factors = parsed_response['data'].map do |auth_factor|
    ::WorkOS::Factor.new(auth_factor.to_json)
  end

  WorkOS::Types::ListStruct.new(
    data: auth_factors,
    list_metadata: parsed_response['list_metadata'],
  )
end

.list_invitations(options = {}) ⇒ WorkOS::Invitation

Retrieve a list of invitations.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • email (String) —

    The email address of a recipient.

  • organization_id (String) —

    The ID of the Organization that the recipient was invited to join.

  • limit (String) —

    Maximum number of records to return.

  • order (String) —

    The order in which to paginate records

  • before (String) —

    Pagination cursor to receive records before a provided User ID.

  • after (String) —

    Pagination cursor to receive records before a provided User ID.

Returns:



1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
 
# File 'lib/workos/user_management.rb', line 1016

def list_invitations(options = {})
  options[:order] ||= 'desc'
  response = execute_request(
    request: get_request(
      path: '/user_management/invitations',
      auth: true,
      params: options,
    ),
  )

  parsed_response = JSON.parse(response.body)

  invitations = parsed_response['data'].map do |invitation|
    ::WorkOS::Invitation.new(invitation.to_json)
  end

  WorkOS::Types::ListStruct.new(
    data: invitations,
    list_metadata: parsed_response['list_metadata'],
  )
end

.list_organization_memberships(options = {}) ⇒ WorkOS::OrganizationMembership

Retrieve a list of Organization Memberships.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • user_id (String) —

    The ID of the User.

  • organization_id (String) —

    Filter memberships by the organization they are members of.

  • statuses (Array<String>) —

    Filter memberships by status.

  • limit (String) —

    Maximum number of records to return.

  • order (String) —

    The order in which to paginate records

  • before (String) —

    Pagination cursor to receive records before a provided User ID.

  • after (String) —

    Pagination cursor to receive records before a provided User ID.

Returns:



857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
 
# File 'lib/workos/user_management.rb', line 857

def list_organization_memberships(options = {})
  options[:order] ||= 'desc'
  response = execute_request(
    request: get_request(
      path: '/user_management/organization_memberships',
      auth: true,
      params: options,
    ),
  )

  parsed_response = JSON.parse(response.body)

  organization_memberships = parsed_response['data'].map do |organization_membership|
    ::WorkOS::OrganizationMembership.new(organization_membership.to_json)
  end

  WorkOS::Types::ListStruct.new(
    data: organization_memberships,
    list_metadata: parsed_response['list_metadata'],
  )
end

.list_users(options = {}) ⇒ WorkOS::User

Retrieve a list of users.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • email (String) —

    Filter Users by their email.

  • organization_id (String) —

    Filter Users by the organization they are members of.

  • limit (String) —

    Maximum number of records to return.

  • order (String) —

    The order in which to paginate records

  • before (String) —

    Pagination cursor to receive records before a provided User ID.

  • after (String) —

    Pagination cursor to receive records before a provided User ID.

Returns:



155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
 
# File 'lib/workos/user_management.rb', line 155

def list_users(options = {})
  options[:order] ||= 'desc'
  response = execute_request(
    request: get_request(
      path: '/user_management/users',
      auth: true,
      params: options,
    ),
  )

  parsed_response = JSON.parse(response.body)

  users = parsed_response['data'].map do |user|
    ::WorkOS::User.new(user.to_json)
  end

  WorkOS::Types::ListStruct.new(
    data: users,
    list_metadata: parsed_response['list_metadata'],
  )
end

.load_sealed_session(client_id:, session_data:, cookie_password:) ⇒ Object

Load a sealed session

Parameters:

  • client_id (String) —

    The WorkOS client ID for the environment

  • session_data (String) —

    The sealed session data

  • cookie_password (String) —

    The password used to seal the session

Returns:

  • WorkOS::Session



47
48
49
50
51
52
53
54
 
# File 'lib/workos/user_management.rb', line 47

def load_sealed_session(client_id:, session_data:, cookie_password:)
  WorkOS::Session.new(
    user_management: self,
    client_id: client_id,
    session_data: session_data,
    cookie_password: cookie_password,
  )
end

.reactivate_organization_membership(id:) ⇒ Object

Reactivate an Organization Membership

Parameters:

  • id (String) —

    The unique ID of the Organization Membership.

Returns:

  • WorkOS::OrganizationMembership



960
961
962
963
964
965
966
967
968
969
 
# File 'lib/workos/user_management.rb', line 960

def reactivate_organization_membership(id:)
  response = execute_request(
    request: put_request(
      path: "/user_management/organization_memberships/#{id}/reactivate",
      auth: true,
    ),
  )

  WorkOS::OrganizationMembership.new(response.body)
end

.reset_password(token:, new_password:) ⇒ Object

Reset user password using token that was sent to the user.

Parameters:

  • token (String) —

    The token that was sent to the user.

  • new_password (String) —

    The new password to set for the user.

Returns:

  • WorkOS::User



812
813
814
815
816
817
818
819
820
821
822
823
824
825
 
# File 'lib/workos/user_management.rb', line 812

def reset_password(token:, new_password:)
  response = execute_request(
    request: post_request(
      path: '/user_management/password_reset/confirm',
      body: {
        token: token,
        new_password: new_password,
      },
      auth: true,
    ),
  )

  WorkOS::User.new(response.body)
end

.revoke_invitation(id:) ⇒ Object

Revokes an existing Invitation.

Parameters:

  • id (String) —

    The unique ID of the Invitation.

Returns:

  • WorkOS::Invitation



1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
 
# File 'lib/workos/user_management.rb', line 1071

def revoke_invitation(id:)
  request = post_request(
    path: "/user_management/invitations/#{id}/revoke",
    auth: true,
  )

  response = execute_request(request: request)

  WorkOS::Invitation.new(response.body)
end

.revoke_session(session_id:) ⇒ Object

Revokes a session

Parameters:

  • session_id (String) —

    The session ID can be found in the ‘sid` claim of the access token



551
552
553
554
555
556
557
558
559
560
561
562
563
 
# File 'lib/workos/user_management.rb', line 551

def revoke_session(session_id:)
  response = execute_request(
    request: post_request(
      path: '/user_management/sessions/revoke',
      body: {
        session_id: session_id,
      },
      auth: true,
    ),
  )

  response.is_a? Net::HTTPSuccess
end

.send_invitation(email:, organization_id: nil, expires_in_days: nil, inviter_user_id: nil, role_slug: nil) ⇒ Object

Sends an Invitation to a recipient.

Must be between 1 and 30, defaults to 7 if not specified.

Parameters:

  • email (String) —

    The email address of the recipient.

  • organization_id (String) (defaults to: nil) —

    The ID of the Organization to which the recipient is being invited.

  • expires_in_days (Integer) (defaults to: nil) —

    The number of days the invitations will be valid for.

  • inviter_user_id (String) (defaults to: nil) —

    The ID of the User sending the invitation.

  • role_slug (String) (defaults to: nil) —

    The slug of the role to assign to the user upon invitation.

Returns:

  • WorkOS::Invitation



1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
 
# File 'lib/workos/user_management.rb', line 1048

def send_invitation(email:, organization_id: nil, expires_in_days: nil, inviter_user_id: nil, role_slug: nil)
  response = execute_request(
    request: post_request(
      path: '/user_management/invitations',
      body: {
        email: email,
        organization_id: organization_id,
        expires_in_days: expires_in_days,
        inviter_user_id: inviter_user_id,
        role_slug: role_slug,
      },
      auth: true,
    ),
  )

  WorkOS::Invitation.new(response.body)
end

.send_magic_auth_code(email:) ⇒ Object

Create a one-time Magic Auth code and emails it to the user.

Parameters:

  • email (String) —

    The email address the one-time code will be sent to.

Returns:

  • Boolean



621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
 
# File 'lib/workos/user_management.rb', line 621

def send_magic_auth_code(email:)
  warn_deprecation '`send_magic_auth_code` is deprecated.
  Please use `create_magic_auth` instead. This method will be removed in a future major version.'

  response = execute_request(
    request: post_request(
      path: '/user_management/magic_auth/send',
      body: {
        email: email,
      },
      auth: true,
    ),
  )

  response.is_a? Net::HTTPSuccess
end

.send_password_reset_email(email:, password_reset_url:) ⇒ Bool

Create a password reset challenge and emails a password reset link to a user.

Parameters:

  • email (String) —

    The email of the user that wishes to reset their password.

  • password_reset_url (String) —

    The URL that will be linked to in the email.

Returns:

  • (Bool) —

    • returns ‘true` if successful



788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
 
# File 'lib/workos/user_management.rb', line 788

def send_password_reset_email(email:, password_reset_url:)
  warn_deprecation '`send_password_reset_email` is deprecated.
  Please use `create_password_reset` instead. This method will be removed in a future major version.'

  request = post_request(
    path: '/user_management/password_reset/send',
    body: {
      email: email,
      password_reset_url: password_reset_url,
    },
    auth: true,
  )

  response = execute_request(request: request)

  response.is_a? Net::HTTPSuccess
end

.send_verification_email(user_id:) ⇒ Object

Sends a verification email to the provided user.

Parameters:

  • user_id (String) —

    The unique ID of the User whose email address will be verified.

Returns:

  • WorkOS::UserResponse



716
717
718
719
720
721
722
723
724
725
 
# File 'lib/workos/user_management.rb', line 716

def send_verification_email(user_id:)
  response = execute_request(
    request: post_request(
      path: "/user_management/users/#{user_id}/email_verification/send",
      auth: true,
    ),
  )

  WorkOS::UserResponse.new(response.body)
end

.update_organization_membership(id:, role_slug:) ⇒ WorkOS::OrganizationMembership

Update an Organization Membership

Parameters:

  • organization_membership_id (String) —

    The ID of the Organization Membership.

  • role_slug (String) —

    The slug of the role to grant to this membership.

Returns:



908
909
910
911
912
913
914
915
916
917
918
919
920
921
 
# File 'lib/workos/user_management.rb', line 908

def update_organization_membership(id:, role_slug:)
  request = put_request(
    path: "/user_management/organization_memberships/#{id}",
    body: {
      id: id,
      role_slug: role_slug,
    },
    auth: true,
  )

  response = execute_request(request: request)

  WorkOS::OrganizationMembership.new(response.body)
end

.update_user(id:, first_name: nil, last_name: nil, email_verified: nil, password: nil, password_hash: nil, password_hash_type: nil) ⇒ WorkOS::User

Update a user

Parameters:

  • id (String) —

    of the user.

  • first_name (String) (defaults to: nil) —

    The user’s first name.

  • last_name (String) (defaults to: nil) —

    The user’s last name.

  • email_verified (Boolean) (defaults to: nil) —

    Whether the user’s email address was previously verified.

  • password (String) (defaults to: nil) —

    The user’s password.

  • password_hash (String) (defaults to: nil) —

    The user’s hashed password.

  • [String] (Hash) —

    a customizable set of options

Returns:



229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
 
# File 'lib/workos/user_management.rb', line 229

def update_user(
  id:,
  first_name: nil,
  last_name: nil,
  email_verified: nil,
  password: nil,
  password_hash: nil,
  password_hash_type: nil
)
  request = put_request(
    path: "/user_management/users/#{id}",
    body: {
      first_name: first_name,
      last_name: last_name,
      email_verified: email_verified,
      password: password,
      password_hash: password_hash,
      password_hash_type: password_hash_type,
    },
    auth: true,
  )

  response = execute_request(request: request)

  WorkOS::User.new(response.body)
end

.verify_email(user_id:, code:) ⇒ Object

Verifiy user email using one-time code that was sent to the user.

Parameters:

  • user_id (String) —

    The unique ID of the User whose email address will be verified.

  • code (String) —

    The one-time code emailed to the user.

Returns:

  • WorkOS::UserResponse



733
734
735
736
737
738
739
740
741
742
743
744
745
 
# File 'lib/workos/user_management.rb', line 733

def verify_email(user_id:, code:)
  response = execute_request(
    request: post_request(
      path: "/user_management/users/#{user_id}/email_verification/confirm",
      body: {
        code: code,
      },
      auth: true,
    ),
  )

  WorkOS::UserResponse.new(response.body)
end