Users API

Provides methods to register, login, and track users for your applications.

For more detailed information on working with users, see the Creating, Updating, Logging In, and Confirmation sections.

See also the OAuth API for managing users with OAuth capabilities.

create

Create a new user, and optionally request an email confirmation.

See also: Creating users, and Confirmation using email.

core.users.create(data_params, listener)

Parameters

Name	Description	Type	Required
data_params	The data parameters for the call.	Table	Y
listener	The api listener callback function.	Function	Y

Data Params

Name	Description	Type	Required
username	The preferred username.	String	Y
password	The users password.	String	Y
email	The users email. User email is required if using email confirmation. See `confirmation` parameter below.	String	N
group	A custom string used to partition this user within the scope.	String	N
extra	A custom data table of key/value pairs to store with the user. Can be of type String, Number, or Boolean only.	Table	N
confirmation	Parameters for optional email confirmation. See the Confirmation section for detailed usage.	Table	N

Important

Passwords are hashed before being sent to the server. Do not try to hash the password yourself.

OAuth Users

To add OAuth provider information to a user, see the addAuthProvider method.

Event Response

On success, the result will hold the created users unique identifier in the user_id key.

Example

local function onUserCreate( evt )
  if evt.error then
    print(evt.error)
  else
    print(evt.result.user_id) -- holds the users id
  end
end

core.users.create({
  username="tiny", 
  password="abcd1234"
}, onUserCreate)

Retrieves the users basic data, and marks a login event in the users database.

You can log a user in with either a username or email (if the user has provided one).

See also: Logging In users, and OAuth Login.

core.users.login(data_params, listener)

Parameters

Name	Description	Type	Required
data_params	The data parameters for the call.	Table	Y
listener	The api listener callback function.	Function	Y

Data Params (Username Login)

Name	Description	Type	Required
username	The registered username.	String	Y
password	The users password.	String	Y

Data Params (Email Login)

Name	Description	Type	Required
email	The registered email.	String	Y
password	The users password.	String	Y

OAuth Login Parameters

To log in a user with an OAuth provider, see OAuth Login.

Event Response

On success, the result will hold a basic login object as a table. See the Logging In section for more details.

Example

Username login

local function onUserLogin( evt )
  if evt.error then
    print(evt.error)
  else
    print(evt.result.user_id) -- result holds the login object
  end
end

core.users.login({username="tiny", password="abcd1234"}, onUserLogin)

Email login

local function onUserLogin( evt )
  if evt.error then
    print(evt.error)
  else
    print(evt.result.user_id) -- result holds the login object
  end
end

core.users.login({email="tina@home.com", password="abcd1234"}, onUserLogin)

get

Get a users full data record. This method does not mark a login event for the user. See login.

core.users.get(data_params, listener)

Parameters

Name	Description	Type	Required
data_params	The data parameters for the call.	Table	Y
listener	The api listener callback function.	Function	Y

Data Params

Name	Description	Type	Required
user_id	The users unique identifier.	String	Y

Event Response

On success, the result will hold the user object as a table.

Example

local function onUserGet( evt )
  if evt.error then
    print(evt.error)
  else
    print(evt.result.user_id) -- result holds the user object
  end
end

core.users.get({user_id="289bc36e-0df7-44df-99b1-a6543c6f45eb"}, onUserGet)

update

Update a users data in the database.

See also: Updating users.

core.users.update(data_params, listener)

Parameters

Name	Description	Type	Required
data_params	The data parameters for the call.	Table	Y
listener	The api listener callback function.	Function	Y

Data Params

Name	Description	Type	Required
user_id	The users unique identifier.	String	Y
update	The user data to update as key/value pairs. See the Updating section for detailed usage.	Table	Y

OAuth Users

To update a users OAuth provider information, see the updateAuthProvider method.

Event Response

On success, the result will hold the updated user object as a table.

Example

local function onUserUpdate( evt )
  if evt.error then
    print(evt.error)
  else
    print(evt.result.user_id) -- result is the updated user object
  end
end

core.users.update({
  user_id = "289bc36e-0df7-44df-99b1-a6543c6f45eb",
  update = {
    email = "some@email.com",
    password = "abcd"
  }
}, onUserUpdate)

delete

Delete a users record from the users database.

core.users.delete(data_params, listener)

Parameters

Name	Description	Type	Required
data_params	The data parameters for the call.	Table	Y
listener	The api listener callback function.	Function	Y

Data Params

Name	Description	Type	Required
user_id	The users unique identifier.	String	Y

OAuth Users

To delete a users OAuth provider information, see the removeAuthProvider method.

Event Response

On success, the result will hold the records removed as a number. Generally a 1 or 0.

Example

local function onUserDelete( evt )
  if evt.error then
    print(evt.error)
  else
    print(evt.result) -- 1 or 0
  end
end

core.users.delete({user_id="289bc36e-0df7-44df-99b1-a6543c6f45eb"}, onUserDelete)

resendConfirmation

Resend the user confirmation email. See Resending Confirmation.

core.users.resendConfirmation(data_params, listener)

Parameters

Name	Description	Type	Required
data_params	The data parameters for the call.	Table	Y
listener	The api listener callback function.	Function	Y

Data Params

Name	Description	Type	Required
user_id	The users unique identifier.	String	Y

Event Response

On success, the result will hold the users unique identifier as a string.

Example

local function onResend( evt )
  if evt.error then
    print(evt.error)
  else
    print(evt.result) -- result holds the users id
  end
end

core.users.resendConfirmation({
  user_id="289bc36e-0df7-44df-99b1-a6543c6f45eb"
}, onResend)

Constants

NULL

Used to remove a key from the users extra metadata (see create). Can only be used with the update method.

core.users.NULL

Example

local function onUserUpdate( evt )
  ...
end

core.users.update({
  user_id = "<user_id>",
  update = {
    extra = {
      color = core.users.NULL --remove the `color` key
    }
  }
}, onUserUpdate)

Viewing Users

You can perform some simple administration and view user statistics in the Webmin.