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) ⇒ Object

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

query parameter in the callback to the Redirect URI.

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.

Returns:

  • WorkOS::AuthenticationResponse



294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
 
# File 'lib/workos/user_management.rb', line 294

def authenticate_with_code(
  code:,
  client_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!,
        ip_address: ip_address,
        user_agent: user_agent,
        grant_type: 'authorization_code',
      },
    ),
  )

  WorkOS::AuthenticationResponse.new(response.body)
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



472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
 
# File 'lib/workos/user_management.rb', line 472

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



362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
 
# File 'lib/workos/user_management.rb', line 362

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



398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
 
# File 'lib/workos/user_management.rb', line 398

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



266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
 
# File 'lib/workos/user_management.rb', line 266

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) ⇒ Object

Authenticate a user using a refresh token.

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.

Returns:

  • WorkOS::RefreshAuthenticationResponse



326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
 
# File 'lib/workos/user_management.rb', line 326

def authenticate_with_refresh_token(
  refresh_token:,
  client_id:,
  organization_id: nil,
  ip_address: nil,
  user_agent: nil
)
  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)
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



435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
 
# File 'lib/workos/user_management.rb', line 435

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) 


77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/workos/user_management.rb', line 77

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



567
568
569
570
571
572
573
574
575
576
577
578
579
580
 
# File 'lib/workos/user_management.rb', line 567

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:



852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
 
# File 'lib/workos/user_management.rb', line 852

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



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

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:



173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/workos/user_management.rb', line 173

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



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

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



894
895
896
897
898
899
900
901
902
903
 
# File 'lib/workos/user_management.rb', line 894

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



246
247
248
249
250
251
252
253
254
255
 
# File 'lib/workos/user_management.rb', line 246

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



615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
 
# File 'lib/workos/user_management.rb', line 615

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



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

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



666
667
668
669
670
671
672
673
674
675
 
# File 'lib/workos/user_management.rb', line 666

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



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

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



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

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:) ⇒ 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

Returns:

  • String



505
506
507
508
509
510
511
 
# File 'lib/workos/user_management.rb', line 505

def get_logout_url(session_id:)
  URI::HTTPS.build(
    host: WorkOS.config.api_hostname,
    path: '/user_management/sessions/logout',
    query: "session_id=#{session_id}",
  ).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



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

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



798
799
800
801
802
803
804
805
806
807
 
# File 'lib/workos/user_management.rb', line 798

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



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

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



115
116
117
118
119
120
121
122
123
124
 
# File 'lib/workos/user_management.rb', line 115

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



641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
 
# File 'lib/workos/user_management.rb', line 641

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:



982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
 
# File 'lib/workos/user_management.rb', line 982

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:



823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
 
# File 'lib/workos/user_management.rb', line 823

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:



139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/workos/user_management.rb', line 139

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

.reactivate_organization_membership(id:) ⇒ Object

Reactivate an Organization Membership

Parameters:

  • id (String) —

    The unique ID of the Organization Membership.

Returns:

  • WorkOS::OrganizationMembership



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

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



778
779
780
781
782
783
784
785
786
787
788
789
790
791
 
# File 'lib/workos/user_management.rb', line 778

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



1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
 
# File 'lib/workos/user_management.rb', line 1037

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



517
518
519
520
521
522
523
524
525
526
527
528
529
 
# File 'lib/workos/user_management.rb', line 517

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



1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
 
# File 'lib/workos/user_management.rb', line 1014

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



587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
 
# File 'lib/workos/user_management.rb', line 587

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



754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
 
# File 'lib/workos/user_management.rb', line 754

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



682
683
684
685
686
687
688
689
690
691
 
# File 'lib/workos/user_management.rb', line 682

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:



874
875
876
877
878
879
880
881
882
883
884
885
886
887
 
# File 'lib/workos/user_management.rb', line 874

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:



213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
 
# File 'lib/workos/user_management.rb', line 213

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



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

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