Skip to content

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.

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)

login

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).

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.

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.