Class: Auth0::Users::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/auth0/users/client.rb

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ void

Parameters:



9
10
11
 
# File 'lib/auth0/users/client.rb', line 9

def initialize(client:)
  @client = client
end

Instance Method Details

#authentication_methods ⇒ Auth0::AuthenticationMethods::Client

Returns:

  • (Auth0::AuthenticationMethods::Client) 


515
516
517
 
# File 'lib/auth0/users/client.rb', line 515

def authentication_methods
  @authentication_methods ||= Auth0::Users::AuthenticationMethods::Client.new(client: @client)
end

#authenticators ⇒ Auth0::Authenticators::Client

Returns:

  • (Auth0::Authenticators::Client) 


520
521
522
 
# File 'lib/auth0/users/client.rb', line 520

def authenticators
  @authenticators ||= Auth0::Users::Authenticators::Client.new(client: @client)
end

#connected_accounts ⇒ Auth0::ConnectedAccounts::Client

Returns:

  • (Auth0::ConnectedAccounts::Client) 


525
526
527
 
# File 'lib/auth0/users/client.rb', line 525

def connected_accounts
  @connected_accounts ||= Auth0::Users::ConnectedAccounts::Client.new(client: @client)
end

#create(request_options: {}, **params) ⇒ Auth0::Types::CreateUserResponseContent

Create a new user for a given database or passwordless connection.

Note: connection is required but other parameters such as email and password are dependent upon the type of connection.

Examples:

client.users.create(connection: "connection")

Parameters:

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Returns:



131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/auth0/users/client.rb', line 131

def create(request_options: {}, **params)
  params = Auth0::Internal::Types::Utils.normalize_keys(params)
  request = Auth0::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "POST",
    path: "users",
    body: Auth0::Users::Types::CreateUserRequestContent.new(params).to_h,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Auth0::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    (response.body.to_s.empty? ? nil : Auth0::Types::CreateUserResponseContent.load(response.body))
  else
    error_class = Auth0::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#delete(request_options: {}, **params) ⇒ untyped

Delete a user by user ID. This action cannot be undone. For Auth0 Dashboard instructions, see Delete Users.

Examples:

client.users.delete(id: "id")

Parameters:

  • request_options (Hash) (defaults to: {})
  • params (Hash)

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

  • :id (String)

Returns:

  • (untyped)

Raises:

  • (error_class) 


276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
 
# File 'lib/auth0/users/client.rb', line 276

def delete(request_options: {}, **params)
  params = Auth0::Internal::Types::Utils.normalize_keys(params)
  request = Auth0::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "DELETE",
    path: "users/#{URI.encode_uri_component(params[:id].to_s)}",
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Auth0::Errors::TimeoutError
  end
  code = response.code.to_i
  return if code.between?(200, 299)

  error_class = Auth0::Errors::ResponseError.subclass_for_code(code)
  raise error_class.new(response.body, code: code)
end

#effective_permissions ⇒ Auth0::EffectivePermissions::Client

Returns:

  • (Auth0::EffectivePermissions::Client) 


530
531
532
 
# File 'lib/auth0/users/client.rb', line 530

def effective_permissions
  @effective_permissions ||= Auth0::Users::EffectivePermissions::Client.new(client: @client)
end

#effective_roles ⇒ Auth0::EffectiveRoles::Client

Returns:

  • (Auth0::EffectiveRoles::Client) 


535
536
537
 
# File 'lib/auth0/users/client.rb', line 535

def effective_roles
  @effective_roles ||= Auth0::Users::EffectiveRoles::Client.new(client: @client)
end

#enrollments ⇒ Auth0::Enrollments::Client

Returns:

  • (Auth0::Enrollments::Client) 


540
541
542
 
# File 'lib/auth0/users/client.rb', line 540

def enrollments
  @enrollments ||= Auth0::Users::Enrollments::Client.new(client: @client)
end

#get(request_options: {}, **params) ⇒ Auth0::Types::GetUserResponseContent

Retrieve user details. A list of fields to include or exclude may also be specified. For more information, see Retrieve Users with the Get Users Endpoint.

Examples:

client.users.get(
  id: "id",
  fields: "fields",
  include_fields: true
)

Parameters:

  • request_options (Hash) (defaults to: {})
  • params (Hash)

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

  • :id (String)
  • :fields (String, nil)
  • :include_fields (Boolean, nil)

Returns:



233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
 
# File 'lib/auth0/users/client.rb', line 233

def get(request_options: {}, **params)
  params = Auth0::Internal::Types::Utils.normalize_keys(params)
  query_params = {}
  query_params["fields"] = params[:fields] if params.key?(:fields)
  query_params["include_fields"] = params[:include_fields] if params.key?(:include_fields)

  request = Auth0::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "GET",
    path: "users/#{URI.encode_uri_component(params[:id].to_s)}",
    query: query_params,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Auth0::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    (response.body.to_s.empty? ? nil : Auth0::Types::GetUserResponseContent.load(response.body))
  else
    error_class = Auth0::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#groups ⇒ Auth0::Groups::Client

Returns:



545
546
547
 
# File 'lib/auth0/users/client.rb', line 545

def groups
  @groups ||= Auth0::Users::Groups::Client.new(client: @client)
end

#identities ⇒ Auth0::Identities::Client

Returns:

  • (Auth0::Identities::Client) 


550
551
552
 
# File 'lib/auth0/users/client.rb', line 550

def identities
  @identities ||= Auth0::Users::Identities::Client.new(client: @client)
end

#list(request_options: {}, **params) ⇒ Auth0::Types::ListUsersOffsetPaginatedResponseContent

Retrieve details of users. It is possible to:

  • Specify a search criteria for users
  • Sort the users to be returned
  • Select the fields to be returned
  • Specify the number of users to retrieve per page and the page index

The q query parameter can be used to get users that match the specified criteria using query string syntax.

Learn more about searching for users.

Read about best practices when working with the API endpoints for retrieving users.

Auth0 limits the number of users you can return. If you exceed this threshold, please redefine your search, use the export job, or the User Import / Export extension.

Examples:

client.users.list(
  page: 1,
  per_page: 1,
  include_totals: true,
  sort: "sort",
  connection: "connection",
  fields: "fields",
  include_fields: true,
  q: "q",
  search_engine: "v1",
  primary_order: true
)

Parameters:

  • request_options (Hash) (defaults to: {})
  • params (Hash)

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

  • :page (Integer, nil)
  • :per_page (Integer, nil)
  • :include_totals (Boolean, nil)
  • :sort (String, nil)
  • :connection (String, nil)
  • :fields (String, nil)
  • :include_fields (Boolean, nil)
  • :q (String, nil)
  • :search_engine (Auth0::Types::SearchEngineVersionsEnum, nil)
  • :primary_order (Boolean, nil)

Returns:



69
70
71
72
73
74
75
76
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
108
109
110
111
 
# File 'lib/auth0/users/client.rb', line 69

def list(request_options: {}, **params)
  params = Auth0::Internal::Types::Utils.normalize_keys(params)
  query_params = {}
  query_params["page"] = params.fetch(:page, 0)
  query_params["per_page"] = params.fetch(:per_page, 50)
  query_params["include_totals"] = params.fetch(:include_totals, true)
  query_params["sort"] = params[:sort] if params.key?(:sort)
  query_params["connection"] = params[:connection] if params.key?(:connection)
  query_params["fields"] = params[:fields] if params.key?(:fields)
  query_params["include_fields"] = params[:include_fields] if params.key?(:include_fields)
  query_params["q"] = params[:q] if params.key?(:q)
  query_params["search_engine"] = params[:search_engine] if params.key?(:search_engine)
  query_params["primary_order"] = params[:primary_order] if params.key?(:primary_order)

  Auth0::Internal::OffsetItemIterator.new(
    initial_page: query_params["page"],
    item_field: :users,
    has_next_field: nil,
    step: false
  ) do |next_page|
    query_params["page"] = next_page
    request = Auth0::Internal::JSON::Request.new(
      base_url: request_options[:base_url],
      method: "GET",
      path: "users",
      query: query_params,
      request_options: request_options
    )
    begin
      response = @client.send(request)
    rescue Net::HTTPRequestTimeout
      raise Auth0::Errors::TimeoutError
    end
    code = response.code.to_i
    if code.between?(200, 299)
      parsed_response = (response.body.to_s.empty? ? nil : Auth0::Types::ListUsersOffsetPaginatedResponseContent.load(response.body))
      [parsed_response, response]
    else
      error_class = Auth0::Errors::ResponseError.subclass_for_code(code)
      raise error_class.new(response.body, code: code)
    end
  end
end

#list_users_by_email(request_options: {}, **params) ⇒ Array[Auth0::Types::UserResponseSchema]

Find users by email. If Auth0 is the identity provider (idP), the email address associated with a user is saved in lower case, regardless of how you initially provided it.

For example, if you register a user as [email protected], Auth0 saves the user's email as [email protected].

Therefore, when using this endpoint, make sure that you are searching for users via email addresses using the correct case.

Examples:

client.users.list_users_by_email(
  fields: "fields",
  include_fields: true,
  email: "email"
)

Parameters:

  • request_options (Hash) (defaults to: {})
  • params (Hash)

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

  • :fields (String, nil)
  • :include_fields (Boolean, nil)
  • :email (String)

Returns:



182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
 
# File 'lib/auth0/users/client.rb', line 182

def list_users_by_email(request_options: {}, **params)
  params = Auth0::Internal::Types::Utils.normalize_keys(params)
  query_params = {}
  query_params["fields"] = params[:fields] if params.key?(:fields)
  query_params["include_fields"] = params[:include_fields] if params.key?(:include_fields)
  query_params["email"] = params[:email] if params.key?(:email)

  request = Auth0::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "GET",
    path: "users-by-email",
    query: query_params,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Auth0::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    Auth0::Internal::Types::Utils.coerce(Internal::Types::Array[Auth0::Types::UserResponseSchema], (response.body.to_s.empty? ? nil : JSON.parse(response.body, symbolize_names: true)))
  else
    error_class = Auth0::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#logs ⇒ Auth0::Logs::Client

Returns:



555
556
557
 
# File 'lib/auth0/users/client.rb', line 555

def logs
  @logs ||= Auth0::Users::Logs::Client.new(client: @client)
end

#multifactor ⇒ Auth0::Multifactor::Client

Returns:

  • (Auth0::Multifactor::Client) 


560
561
562
 
# File 'lib/auth0/users/client.rb', line 560

def multifactor
  @multifactor ||= Auth0::Users::Multifactor::Client.new(client: @client)
end

#organizations ⇒ Auth0::Organizations::Client

Returns:



565
566
567
 
# File 'lib/auth0/users/client.rb', line 565

def organizations
  @organizations ||= Auth0::Users::Organizations::Client.new(client: @client)
end

#permissions ⇒ Auth0::Permissions::Client

Returns:

  • (Auth0::Permissions::Client) 


570
571
572
 
# File 'lib/auth0/users/client.rb', line 570

def permissions
  @permissions ||= Auth0::Users::Permissions::Client.new(client: @client)
end

#refresh_token ⇒ Auth0::RefreshToken::Client

Returns:

  • (Auth0::RefreshToken::Client) 


585
586
587
 
# File 'lib/auth0/users/client.rb', line 585

def refresh_token
  @refresh_token ||= Auth0::Users::RefreshToken::Client.new(client: @client)
end

#regenerate_recovery_code(request_options: {}, **params) ⇒ Auth0::Types::RegenerateUsersRecoveryCodeResponseContent

Remove an existing multi-factor authentication (MFA) recovery code and generate a new one. If a user cannot access the original device or account used for MFA enrollment, they can use a recovery code to authenticate.

Examples:

client.users.regenerate_recovery_code(id: "id")

Parameters:

  • request_options (Hash) (defaults to: {})
  • params (Hash)

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

  • :id (String)

Returns:



452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
 
# File 'lib/auth0/users/client.rb', line 452

def regenerate_recovery_code(request_options: {}, **params)
  params = Auth0::Internal::Types::Utils.normalize_keys(params)
  request = Auth0::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "POST",
    path: "users/#{URI.encode_uri_component(params[:id].to_s)}/recovery-code-regeneration",
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Auth0::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    (response.body.to_s.empty? ? nil : Auth0::Types::RegenerateUsersRecoveryCodeResponseContent.load(response.body))
  else
    error_class = Auth0::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end

#revoke_access(request_options: {}, **params) ⇒ untyped

Revokes selected resources related to a user (sessions, refresh tokens, ...).

Examples:

client.users.revoke_access(id: "id")

Parameters:

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

  • :id (String)

Returns:

  • (untyped)

Raises:

  • (error_class) 


489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
 
# File 'lib/auth0/users/client.rb', line 489

def revoke_access(request_options: {}, **params)
  params = Auth0::Internal::Types::Utils.normalize_keys(params)
  request_data = Auth0::Users::Types::RevokeUserAccessRequestContent.new(params).to_h
  non_body_param_names = %w[id]
  body = request_data.except(*non_body_param_names)

  request = Auth0::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "POST",
    path: "users/#{URI.encode_uri_component(params[:id].to_s)}/revoke-access",
    body: body,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Auth0::Errors::TimeoutError
  end
  code = response.code.to_i
  return if code.between?(200, 299)

  error_class = Auth0::Errors::ResponseError.subclass_for_code(code)
  raise error_class.new(response.body, code: code)
end

#risk_assessments ⇒ Auth0::RiskAssessments::Client

Returns:



575
576
577
 
# File 'lib/auth0/users/client.rb', line 575

def risk_assessments
  @risk_assessments ||= Auth0::Users::RiskAssessments::Client.new(client: @client)
end

#roles ⇒ Auth0::Roles::Client

Returns:



580
581
582
 
# File 'lib/auth0/users/client.rb', line 580

def roles
  @roles ||= Auth0::Users::Roles::Client.new(client: @client)
end

#sessions ⇒ Auth0::Sessions::Client

Returns:



590
591
592
 
# File 'lib/auth0/users/client.rb', line 590

def sessions
  @sessions ||= Auth0::Users::Sessions::Client.new(client: @client)
end

#update(request_options: {}, **params) ⇒ Auth0::Types::UpdateUserResponseContent

Update a user.

These are the attributes that can be updated at the root level:

  • app_metadata
  • blocked
  • email
  • email_verified
  • family_name
  • given_name
  • name
  • nickname
  • password
  • phone_number
  • phone_verified
  • picture
  • username
  • user_metadata
  • verify_email

Some considerations:

  • The properties of the new object will replace the old ones.
  • The metadata fields are an exception to this rule (user_metadata and app_metadata). These properties are merged instead of being replaced but be careful, the merge only occurs on the first level.
  • If you are updating email, email_verified, phone_number, phone_verified, username or password of a secondary identity, you need to specify the connection property too.
  • If you are updating email or phone_number you can specify, optionally, the client_id property.
  • Updating email_verified is not supported for enterprise and passwordless sms connections.
  • Updating the blocked to false does not affect the user's blocked state from an excessive amount of incorrectly provided credentials. Use the "Unblock a user" endpoint from the "User Blocks" API to change the user's state.
  • Supported attributes can be unset by supplying null as the value.

Updating a field (non-metadata property)

To mark the email address of a user as verified, the body to send should be:

{ "email_verified": true }

Updating a user metadata root property

Let's assume that our test user has the following user_metadata:

{ "user_metadata" : { "profileCode": 1479 } }

To add the field addresses the body to send should be:

{ "user_metadata" : { "addresses": {"work_address": "100 Industrial Way"} }}

The modified object ends up with the following user_metadata property:

{
  "user_metadata": {
    "profileCode": 1479,
    "addresses": { "work_address": "100 Industrial Way" }
  }
}

Updating an inner user metadata property

If there's existing user metadata to which we want to add "home_address": "742 Evergreen Terrace" (using the addresses property) we should send the whole addresses object. Since this is a first-level object, the object will be merged in, but its own properties will not be. The body to send should be:

{
  "user_metadata": {
    "addresses": {
      "work_address": "100 Industrial Way",
      "home_address": "742 Evergreen Terrace"
    }
  }
}

The modified object ends up with the following user_metadata property:

{
  "user_metadata": {
    "profileCode": 1479,
    "addresses": {
      "work_address": "100 Industrial Way",
      "home_address": "742 Evergreen Terrace"
    }
  }
}

Examples:

client.users.update(id: "id")

Parameters:

Options Hash (request_options:):

  • :base_url (String)
  • :additional_headers (Hash{String => Object})
  • :additional_query_parameters (Hash{String => Object})
  • :additional_body_parameters (Hash{String => Object})
  • :timeout_in_seconds (Integer)

Options Hash (**params):

  • :id (String)

Returns:



407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
 
# File 'lib/auth0/users/client.rb', line 407

def update(request_options: {}, **params)
  params = Auth0::Internal::Types::Utils.normalize_keys(params)
  request_data = Auth0::Users::Types::UpdateUserRequestContent.new(params).to_h
  non_body_param_names = %w[id]
  body = request_data.except(*non_body_param_names)

  request = Auth0::Internal::JSON::Request.new(
    base_url: request_options[:base_url],
    method: "PATCH",
    path: "users/#{URI.encode_uri_component(params[:id].to_s)}",
    body: body,
    request_options: request_options
  )
  begin
    response = @client.send(request)
  rescue Net::HTTPRequestTimeout
    raise Auth0::Errors::TimeoutError
  end
  code = response.code.to_i
  if code.between?(200, 299)
    (response.body.to_s.empty? ? nil : Auth0::Types::UpdateUserResponseContent.load(response.body))
  else
    error_class = Auth0::Errors::ResponseError.subclass_for_code(code)
    raise error_class.new(response.body, code: code)
  end
end