Module: Auth0::Api::V2::Users

Includes:
Mixins::Validation
Included in:
Auth0::Api::V2
Defined in:
lib/auth0/api/v2/users.rb

Overview

Methods to use the users endpoints

Instance Method Summary collapse

Methods included from Mixins::Validation

#validate_permissions_array, #validate_strings_array

Instance Method Details

#add_user_permissions(user_id, permissions) ⇒ Object

Add one or more permissions from a specific user.

Parameters:

  • user_id (string) —

    The user_id of the permissions to add.

  • permissions (array) —

    An array of Permission structs to add.

Raises:

See Also:



296
297
298
299
300
 
# File 'lib/auth0/api/v2/users.rb', line 296

def add_user_permissions(user_id, permissions)
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
  permissions = validate_permissions_array permissions
  post "#{users_path}/#{user_id}/permissions", permissions: permissions
end

#add_user_roles(user_id, roles) ⇒ Object

Add one or more roles to a specific user.

Parameters:

  • user_id (string) —

    The user_id of the roles to add.

  • roles (array) —

    An array of role ids to add.

Raises:

See Also:



240
241
242
243
244
245
 
# File 'lib/auth0/api/v2/users.rb', line 240

def add_user_roles(user_id, roles)
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
  validate_strings_array roles
  path = "#{users_path}/#{user_id}/roles"
  post(path, roles: roles)
end

#create_user(connection, options = {}) ⇒ json

Creates a new user according to optional parameters received. The attribute connection is always mandatory but depending on the type of connection you are using there could be others too. For instance, Auth0 DB Connections require email and password.

Parameters:

Returns:

  • (json) —

    Returns the created user.

See Also:



49
50
51
52
53
54
55
56
 
# File 'lib/auth0/api/v2/users.rb', line 49

def create_user(connection, options = {})
  if !connection.is_a?(String) || connection.empty?
    raise Auth0::MissingParameter, 'Must supply a valid connection'
  end
  request_params = Hash[options.map { |(k, v)| [k.to_sym, v] }]
  request_params[:connection] = connection
  post(users_path, request_params)
end

#delete_user(user_id) ⇒ Object

Deletes a single user given its id

Parameters:

  • user_id (string) —

    The user_id of the user to delete.

Raises:

See Also:



84
85
86
87
88
 
# File 'lib/auth0/api/v2/users.rb', line 84

def delete_user(user_id)
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
  path = "#{users_path}/#{user_id}"
  delete(path)
end

#delete_user_authentication_method(user_id, authentication_method_id) ⇒ Object

Deletes the user’s authentication method specified by authentication_method_id

Parameters:

  • user_id (string) —

    The user ID

  • authentication_method_id (string) —

    The ID of the authentication method

Raises:

See Also:



441
442
443
444
445
446
 
# File 'lib/auth0/api/v2/users.rb', line 441

def delete_user_authentication_method(user_id, authentication_method_id)
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
  raise Auth0::MissingParameter, 'Must supply an authentication_method_id' if authentication_method_id.to_s.empty?

  delete "#{users_path}/#{user_id}/authentication-methods/#{authentication_method_id}"
end

#delete_user_authentication_methods(user_id) ⇒ Object

Deletes all of the user’s authentication methods

Parameters:

  • user_id (string) —

    The user ID

Raises:

See Also:



429
430
431
432
433
 
# File 'lib/auth0/api/v2/users.rb', line 429

def delete_user_authentication_methods(user_id)
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?

  delete "#{users_path}/#{user_id}/authentication-methods"          
end

#delete_user_authenticators(user_id) ⇒ Object

Delete all authenticators

Parameters:

  • user_id (string) —

    The user_id of the user to delete all authenticators

Raises:

See Also:



117
118
119
120
121
 
# File 'lib/auth0/api/v2/users.rb', line 117

def delete_user_authenticators(user_id)
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
  path = "#{users_path}/#{user_id}/authenticators"
  delete(path)
end

#delete_user_provider(user_id, provider_name) ⇒ Object

Delete a user’s multifactor provider

Parameters:

  • user_id (string) —

    The user_id of the user to delete the multifactor provider from.

  • provider_name (string) —

    The multifactor provider. Supported values ‘duo’ or ‘google-authenticator’.

Raises:

See Also:



127
128
129
130
131
132
 
# File 'lib/auth0/api/v2/users.rb', line 127

def delete_user_provider(user_id, provider_name)
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
  raise Auth0::InvalidParameter, 'Must supply a valid provider name' if provider_name.to_s.empty?
  path = "#{users_path}/#{user_id}/multifactor/#{provider_name}"
  delete(path)
end

#delete_user_sessions(user_id) ⇒ Object

Delete all sessions for a user.

Parameters:

  • user_id (string) —

    The user ID

Raises:

See Also:



452
453
454
455
456
 
# File 'lib/auth0/api/v2/users.rb', line 452

def delete_user_sessions(user_id)
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?

  delete "#{users_path}/#{user_id}/sessions"
end

#delete_users ⇒ Object

Deprecated.

  • 4.8.0, endpoint has been removed

Delete all users - USE WITH CAUTION



60
61
62
 
# File 'lib/auth0/api/v2/users.rb', line 60

def delete_users
  delete(users_path)
end

#generate_recovery_code(user_id) ⇒ Object

Remove the current Guardian recovery code and generates and returns a new one.

Parameters:

  • user_id (string) —

    The user_id of the recovery codes to regenerate.

Raises:

See Also:



306
307
308
309
 
# File 'lib/auth0/api/v2/users.rb', line 306

def generate_recovery_code(user_id)
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
  post "#{users_path}/#{user_id}/recovery-code-regeneration"
end

#get_enrollments(user_id) ⇒ json

Get all Guardian enrollments for a specific user

Parameters:

  • user_id (string) —

    The user_id of the enrollments to get.

Returns:

  • (json) —

    Returns Guardian enrollments for the given user_id.

Raises:

See Also:



253
254
255
256
 
# File 'lib/auth0/api/v2/users.rb', line 253

def get_enrollments(user_id)
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
  get "#{users_path}/#{user_id}/enrollments"
end

#get_user_organizations(user_id) ⇒ json

Get a list of organizations for a user.

Parameters:

  • user_id (string) —

    The user_id of the permissions to get.

Returns:

  • (json) —

    Returns organizations for the given user_id.

Raises:



326
327
328
329
330
 
# File 'lib/auth0/api/v2/users.rb', line 326

def get_user_organizations(user_id)
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?

  get "#{users_path}/#{user_id}/organizations"
end

#get_user_permissions(user_id, options = {}) ⇒ json

Get all permissions for a specific user.

Parameters:

  • user_id (string) —

    The user_id of the permissions to get.

  • options (hash) (defaults to: {}) —

    A hash of options for getting permissions

    • :per_page [integer] The amount of permissions per page. (optional)

    • :page [integer] The page number. Zero based. (optional)

    • :include_totals [boolean] True if a query summary must be included in the result. (optional)

Returns:

  • (json) —

    Returns permissions for the given user_id.

Raises:

See Also:



268
269
270
271
272
273
274
275
276
277
278
 
# File 'lib/auth0/api/v2/users.rb', line 268

def get_user_permissions(user_id, options = {})
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?

  request_params = {
    per_page: options.fetch(:per_page, nil),
    page: options.fetch(:page, nil),
    include_totals: options.fetch(:include_totals, nil)
  }

  get "#{users_path}/#{user_id}/permissions", request_params
end

#get_user_roles(user_id, options = {}) ⇒ json

Get all roles assigned to a specific user.

Parameters:

  • user_id (string) —

    The user_id of the roles to retrieve.

  • options (hash) (defaults to: {}) —

    • :per_page [integer] The amount of entries per page. Default: 50. Max value: 100.

    • :page [integer] The page number. Zero based.

    • :include_totals [boolean] True if a query summary must be included in the result.

    • :sort [string] The field to use for sorting. 1 == ascending and -1 == descending.

Returns:

  • (json) —

    Returns roles for the given user_id.

Raises:

See Also:



212
213
214
215
216
217
218
219
220
221
 
# File 'lib/auth0/api/v2/users.rb', line 212

def get_user_roles(user_id, options = {})
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
  path = "#{users_path}/#{user_id}/roles"
  request_params = {
    per_page:       options.fetch(:per_page, nil),
    page:           options.fetch(:page, nil),
    include_totals: options.fetch(:include_totals, nil)
  }
  get(path, request_params)
end

#invalidate_browsers(user_id) ⇒ Object

Invalidate all remembered browsers for all authentication factors for a specific user.

Parameters:

  • user_id (string) —

    The user_id of the browsers to invalidate.

Raises:

See Also:



315
316
317
318
 
# File 'lib/auth0/api/v2/users.rb', line 315

def invalidate_browsers(user_id)
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
  post "#{users_path}/#{user_id}/multifactor/actions/invalidate-remember-browser"
end

#link_user_account(user_id, body) ⇒ json

Links the account specified in the body (secondary account) to the account specified by the id param of the URL (primary account).

  1. With the authenticated primary account’s JWT in the Authorization header, which has the

update:current_user_identities scope. In this case only the link_with param is required in the body, containing the JWT obtained upon the secondary account’s authentication.

  1. With an API V2 generated token with update:users scope. In this case you need to send provider and user_id

in the body. Optionally you can also send the connection_id param which is suitable for identifying a particular database connection for the ‘auth0’ provider.

Parameters:

  • user_id (string) —

    The user_id of the primary identity where you are linking the secondary account to.

  • body (string) —

    the options to link the account to.

Returns:

  • (json) —

    Returns the new array of the primary account identities.

Raises:

See Also:



147
148
149
150
151
152
 
# File 'lib/auth0/api/v2/users.rb', line 147

def (user_id, body)
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
  raise Auth0::InvalidParameter, 'Must supply a valid body' if body.to_s.empty?
  path = "#{users_path}/#{user_id}/identities"
  post(path, body)
end

#patch_user(user_id, body) ⇒ json Also known as: update_user

Updates a user with the object’s properties received in the optional parameters. These are the attributes that can be updated at the root level: blocked, email_verified, email, verify_email, password, phone_number, phone_verified, verify_password, user_metadata, app_metadata, username 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_verified, phone_verified, username or password you need to specify the connection property too. If your are updating email or phone_number you need to specify the connection and the client_id properties.

Parameters:

  • user_id (string) —

    The user_id of the user to update.

  • body (hash) —

    The optional parameters to update.

Returns:

  • (json) —

    Returns the updated user.

Raises:

See Also:



106
107
108
109
110
111
 
# File 'lib/auth0/api/v2/users.rb', line 106

def patch_user(user_id, body)
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
  raise Auth0::InvalidParameter, 'Must supply a valid body' if body.to_s.empty? || body.empty?
  path = "#{users_path}/#{user_id}"
  patch(path, body)
end

#patch_user_authentication_method(user_id, authentication_method_id, body) ⇒ Object Also known as: update_user_authentication_method

Updates a user authentication method

Parameters:

  • user_id (string) —

    The user ID of the authentication methods to get

  • body (hash array) —

    The mehods to update

    • :name [string] A human-readable label to identify the authentication method (optional)

    • :preferred_authentication_method [string] Preferred phone authentication method (optional)

Raises:

See Also:



416
417
418
419
420
421
422
 
# File 'lib/auth0/api/v2/users.rb', line 416

def patch_user_authentication_method(user_id, authentication_method_id, body)
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
  raise Auth0::MissingParameter, 'Must supply an authentication_method_id' if authentication_method_id.to_s.empty?
  raise Auth0::MissingParameter, 'Must supply a body' if body.to_s.empty?

  patch "#{users_path}/#{user_id}/authentication-methods/#{authentication_method_id}", body
end

#post_user_authentication_method(user_id, body) ⇒ Object Also known as: create_user_authentication_method

Create an authentication method for a user

Parameters:

  • user_id (string) —

    The user ID of the authentication methods to get

  • body (hash) —

    The post body content

    • :type [string] “phone” or “email” or “totp” or “webauthn-roaming”

    • :name [string] A human-readable label to identify the authentication method (optional)

    • :totp_secret [string] Base32 encoded secret for TOTP generation (optional)

    • :phone_number [string] Applies to phone authentication methods only. The destination phone number used to send verification codes via text and voice (optional)

    • :email [string] Applies to email authentication methods only. The email address used to send verification messages (optional)

    • :preferred_authentication_method [string] Preferred phone authentication method (optional)

    • :key_id [string] Applies to email webauthn authenticators only. The id of the credential (optional)

    • :public_key [string] Applies to email webauthn authenticators only. The public key (optional)

    • :relying_party_identifier [string] Applies to email webauthn authenticators only. The relying party identifier (optional)

Raises:

See Also:



382
383
384
385
386
387
 
# File 'lib/auth0/api/v2/users.rb', line 382

def post_user_authentication_method(user_id, body)
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
  raise Auth0::MissingParameter, 'Must supply a body' if body.to_s.empty?

  post "#{users_path}/#{user_id}/authentication-methods", body
end

#put_all_user_authentication_methods(user_id, body) ⇒ Object Also known as: update_all_user_authentication_methods

Updates all authentication methods by replacing them with the given ones

Parameters:

  • user_id (string) —

    The user ID of the authentication methods to get

  • body (hash array) —

    The mehods to update

    • :type [string] “phone” or “email” or “totp” or “webauthn-roaming”

    • :name [string] A human-readable label to identify the authentication method (optional)

    • :totp_secret [string] Base32 encoded secret for TOTP generation (optional)

    • :phone_number [string] Applies to phone authentication methods only. The destination phone number used to send verification codes via text and voice (optional)

    • :email [string] Applies to email authentication methods only. The email address used to send verification messages (optional)

    • :preferred_authentication_method [string] Preferred phone authentication method (optional)

Raises:

See Also:



401
402
403
404
405
406
 
# File 'lib/auth0/api/v2/users.rb', line 401

def put_all_user_authentication_methods(user_id, body)
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
  raise Auth0::MissingParameter, 'Must supply a body' if body.to_s.empty?

  put "#{users_path}/#{user_id}/authentication-methods", body
end

#remove_user_permissions(user_id, permissions) ⇒ Object

Remove one or more permissions from a specific user.

Parameters:

  • user_id (string) —

    The user_id of the permissions to remove.

  • permissions (array) —

    An array of Permission structs to remove.

Raises:

See Also:



285
286
287
288
289
 
# File 'lib/auth0/api/v2/users.rb', line 285

def remove_user_permissions(user_id, permissions)
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
  permissions = validate_permissions_array permissions
  delete_with_body "#{users_path}/#{user_id}/permissions", permissions: permissions
end

#remove_user_roles(user_id, roles) ⇒ Object

Remove one or more roles from a specific user.

Parameters:

  • user_id (string) —

    The user_id of the roles to remove.

  • roles (array) —

    An array of role ids to remove.

Raises:

See Also:



228
229
230
231
232
233
 
# File 'lib/auth0/api/v2/users.rb', line 228

def remove_user_roles(user_id, roles)
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
  validate_strings_array roles
  path = "#{users_path}/#{user_id}/roles"
  delete_with_body path, roles: roles
end

#unlink_user_account(user_id, provider, secondary_user_id) ⇒ json Also known as: unlink_users_account

Unlink a user account

Parameters:

  • user_id (string) —

    The user_id of the user identity.

  • provider (string) —

    The type of identity provider.

  • secondary_user_id (string) —

    The unique identifier for the user for the identity.

Returns:

  • (json) —

    Returns the array of the unlinked account identities.

Raises:

See Also:



161
162
163
164
165
166
167
 
# File 'lib/auth0/api/v2/users.rb', line 161

def (user_id, provider, secondary_user_id)
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
  raise Auth0::MissingUserId, 'Must supply a valid secondary user_id' if secondary_user_id.to_s.empty?
  raise Auth0::InvalidParameter, 'Must supply a valid provider' if provider.to_s.empty?
  path = "#{users_path}/#{user_id}/identities/#{provider}/#{secondary_user_id}"
  delete(path)
end

#user(user_id, fields: nil, include_fields: true) ⇒ json

Retrieves a user given a user_id

Parameters:

  • user_id (string) —

    The user_id of the user to retrieve.

  • fields (string) (defaults to: nil) —

    A comma separated list of fields to include or exclude from the result.

  • include_fields (boolean) (defaults to: true) —

    True if the fields specified are to be included in the result, false otherwise.

Returns:

  • (json) —

    Returns the user with the given user_id if it exists.

Raises:

See Also:



71
72
73
74
75
76
77
78
79
 
# File 'lib/auth0/api/v2/users.rb', line 71

def user(user_id, fields: nil, include_fields: true)
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
  path = "#{users_path}/#{user_id}"
  request_params = {
    fields:         fields,
    include_fields: include_fields
  }
  get(path, request_params)
end

#user_authentication_method(user_id, authentication_method_id) ⇒ json Also known as: get_user_authentication_method

Get a specific authentication method for a user.

Parameters:

  • user_id (string) —

    The user ID of the authentication methods to get

  • authentication_method_id (string) —

    The ID of the authentication method

Returns:

  • (json) —

    The user authentication method

Raises:

See Also:



360
361
362
363
364
365
 
# File 'lib/auth0/api/v2/users.rb', line 360

def user_authentication_method(user_id, authentication_method_id)
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
  raise Auth0::MissingParameter, 'Must supply a valid authentication_method_id' if authentication_method_id.to_s.empty?

  get "#{users_path}/#{user_id}/authentication-methods/#{authentication_method_id}"
end

#user_authentication_methods(user_id, options = {}) ⇒ json Also known as: get_user_authentication_methods

Get the available authentication methods for a user.

Parameters:

  • user_id (string) —

    The user ID of the authentication methods to get

  • options (hash) (defaults to: {}) —

    A hash of options for getting permissions

    • :per_page [integer] The amount of permissions per page. (optional)

    • :page [integer] The page number. Zero based. (optional)

    • :include_totals [boolean] True if a query summary must be included in the result. (optional)

Returns:

  • (json) —

    The user’s authentication methods

Raises:

See Also:



341
342
343
344
345
346
347
348
349
350
351
 
# File 'lib/auth0/api/v2/users.rb', line 341

def user_authentication_methods(user_id, options = {})
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?

  request_params = {
    per_page: options.fetch(:per_page, nil),
    page: options.fetch(:page, nil),
    include_totals: options.fetch(:include_totals, nil)
  }

  get "#{users_path}/#{user_id}/authentication-methods", request_params
end

#user_logs(user_id, options = {}) ⇒ json Also known as: get_user_log_events

Retrieve every log event for a specific user id rubocop:disable Metrics/MethodLength, Metrics/AbcSize

Parameters:

  • user_id (string) —

    The user_id of the logs to retrieve.

  • options (hash) (defaults to: {}) —

    • :per_page [integer] The amount of entries per page. Default: 50. Max value: 100.

    • :page [integer] The page number. Zero based.

    • :include_totals [boolean] True if a query summary must be included in the result.

    • :sort [string] The field to use for sorting. 1 == ascending and -1 == descending.

Returns:

  • (json) —

    Returns the list of existing log entries for the given user_id.

Raises:

See Also:



181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
 
# File 'lib/auth0/api/v2/users.rb', line 181

def user_logs(user_id, options = {})
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?
  path = "#{users_path}/#{user_id}/logs"
  request_params = {
    per_page:       options.fetch(:per_page, nil),
    page:           options.fetch(:page, nil),
    include_totals: options.fetch(:include_totals, nil),
    sort:           options.fetch(:sort, nil)
  }
  if request_params[:per_page].to_i > 100
    raise Auth0::InvalidParameter, 'The total amount of entries per page should be less than 100'
  end
  sort_pattern = /^(([a-zA-Z0-9_\.]+))\:(1|-1)$/
  if !request_params[:sort].nil? && !sort_pattern.match(request_params[:sort])
    raise Auth0::InvalidParameter, 'Sort does not match pattern ^(([a-zA-Z0-9_\\.]+))\\:(1|-1)$'
  end
  get(path, request_params)
end

#user_sessions(user_id) ⇒ Object

Retrieve details for a user’s sessions.

Parameters:

  • user_id (string) —

    The user ID

Raises:

See Also:



462
463
464
465
466
 
# File 'lib/auth0/api/v2/users.rb', line 462

def user_sessions(user_id)
  raise Auth0::MissingUserId, 'Must supply a valid user_id' if user_id.to_s.empty?

  get "#{users_path}/#{user_id}/sessions"
end

#users(options = {}) ⇒ json Also known as: get_users

Retrieves a list of Auth0 users.

Parameters:

  • options (hash) (defaults to: {}) —

    The Hash options used to refine the User results.

    • :per_page [integer] The amount of entries per page. Default: 50. Max value: 100.

    • :page [integer] The page number. Zero based.

    • :include_totals [boolean] True if a query summary must be included in the result.

    • :sort [string] The field to use for sorting. 1 == ascending and -1 == descending.

    • :connection [string] Connection to filter results by.

    • :fields [string] A comma separated list of result fields.

    • :include_fields [boolean] True to include :fields, false to exclude.

    • :q [string] Query in Lucene query string syntax.

    • :search_engine [string] User search engine version.

Returns:

  • (json) —

    Returns the list of existing users.

See Also:



26
27
28
29
30
31
32
33
34
35
36
37
38
39
 
# File 'lib/auth0/api/v2/users.rb', line 26

def users(options = {})
  request_params = {
    per_page:       options.fetch(:per_page, nil),
    page:           options.fetch(:page, nil),
    include_totals: options.fetch(:include_totals, nil),
    sort:           options.fetch(:sort, nil),
    connection:     options.fetch(:connection, nil),
    fields:         options.fetch(:fields, nil),
    include_fields: options.fetch(:include_fields, nil),
    q:              options.fetch(:q, nil),
    search_engine:  options.fetch(:search_engine, nil)
  }
  get(users_path, request_params)
end