Users API

Provides methods to build a custom user registration flow on the server-side that integrates with the Coronium Core user system, as well as, advanced user queries. You can also use OAuth client IDs as user identifiers via the OAuth API.

Advanced Usage

These methods are for advanced use cases. In general you should use the client-side Users module for your user management.

register

Registers a new user into the Coronium user system. This method marks a "join" event for statistical purposes.

The user is automatically marked as confirmed and active. Email confirmations are not supported through this method. See the client-side Users module instead if you need email confirmations.

Users created using the server-side register method are not able to log in using the client-side login method. You must create a custom server-side API method and log the user in using the server-side login method. See the login method below.

core.users.register(username, password, scope, meta)

Parameters

Name	Description	Type	Required
username	An optional display name for the user. To create an anonymous user pass nil to this parameter, and a generic name will automatically be created.	String or Nil	Y
password	An optional password for the user. To create a user without a password, pass nil to this parameter. Anonymous users cannot have passwords, so if you pass nil for the username, you must pass nil here as well.	String or Nil	Y
scope	The application scope this user should belong to. To get the current client application scope see the Input section of the API module, or supply your own.	String	Y
meta	Addtional information for the user registration (see Meta Keys below).	Table	N

Important

String values are automatically run through mysql.escape. Do not double-escape values.

Passwords

Supply the password as plain text. It will be hashed before being added to the user record.

Meta Keys

The following keys are currently supported in the meta table:

• email (string)
• group (string)
• extra (table)
• login (boolean)

The login key, when set to true, will mark a "login" in addition to a "join" event when the user is created. The default is false. This can be helpful when conditionally creating new users. See also login.

The extra key is a key/value based table that you can use to store additional custom data to the user record. The extra table can only contain String, Number, and Boolean data types.

The full meta table structure looks like:

--meta table
{
  email = "me@home.com",
  group = "cadets",
  extra = {
    color = "Blue",
    age = 24,
    winner = true
  },
  login = true
}

Anonymous Users

If you create an anonymous user (see examples below), you must add an OAuth provider using addAuthProvider to be able to log the user in.

Returns

The newly created users unique ID as a string, or nil, error, and error code.

Example

--Custom server-side API (main.lua)
local api = core.api()

--api methods have an additonal argument
--called `scope` that contains the 
--scope for the current client call.
function api.registerUser(input, scope)

  -- Example 1
  -- Create an anonymous user. You must add an OAuth provider
  -- to be able to log this user in.
  local user_id, err, code = core.users.register(nil, nil, scope)

  --== Add an OAuth provider here with the returned user_id.

  -- Example 2
  -- Create an anonymous user, with email and group. You must add an OAuth provider
  -- to be able to log this user in.
  local user_id, err, code = core.users.register(nil, nil, scope, {
    group = "cadets",
    email = "me@home.com"
  })

  --== Add an OAuth provider here with the returned user_id.

  -- Example 3
  -- Create a named user, no password.
  local user_id, err, code = core.users.register("Donna", nil, scope)

  -- Example 4
  -- Create a named user with password.
  local user_id, err, code = core.users.register("Donna", "mypass123", scope)

  -- Example 5
  -- Create a named user, with email and extra.
  local user_id, err, code = core.users.register("Billy", nil, scope, {
    email = "me@home.com",
    extra = {
      color = "Green",
      age = 36
    }
  })

  -- Example 6
  -- Create an named user in a different scope, with extra.
  local user_id, err, code = core.users.register("Bob", nil, "Space Race", {
    extra = {
      likes_pizza = true
    }
  })

  -- Handle any errors by logging
  if not user_id then
    core.log(err)
  end

  --OR

  --Pass the err and code downstream
  if not user_id then
    return core.error(err, code)
  end

  --Return something on success
  return true

end

return api

Errors Codes

The Users module methods return a string error as well as a error "status" code. You can use these codes to adjust your application logic. A listing of current error codes can be found in the Status Codes section. The codes are generally more helpful on the client-side.

Linking OAuth Providers

See the OAuth API to learn how to associate your Coronium users OAuth providers.

login

Login a user with a username (with or without password), user_id, or OAuth client_id. This method marks a "login" event for statistical purposes.

core.users.login(login_type)

Parameters

Name	Description	Type	Required
login_type	A key/value table. See example below.	Table	Y

Important

String values are automatically run through mysql.escape. Do not double-escape values.

Returns

A user record as a table, or nil, error and error code.

Example

-- By username and password
local user, err, code = core.users.login({
  username='Timmy', 
  password = 'pass1234',
  scope='Fun Run'
})

-- By username
local user, err, code = core.users.login({
  username='Timmy', 
  scope='Fun Run'
})

--By OAuth ID
local user, err, code = core.users.login({
  provider = core.FACEBOOK,
  client_id="fb_id-1234", 
  scope='Space Race'
})

--By User ID
local user, err, code = core.users.login({
  user_id="aad3eba3-9c9c-9a1b-f236de1e3752"
})

update

Update a user in the Coronium user system. If you do not have a user_id, first use the users.getWithQuery method to get one.

core.users.update(user_id, update_params)

Updating OAuth

To update OAuth provider information for a user see the updateAuthProvider method.

Parameters

Name	Description	Type	Required
user_id	The users unique identifier.	String	Y
update_params	A table of key/value pairs to update.	Table	Y

Important

String values are automatically run through mysql.escape. Do not double-escape values.

The following keys are updatable:

• username (string)
• password (string)
• email (string)
• group (string)
• extra (table)
• active (boolean)

Updating Passwords

Supply the password as plain text. It will be hashed before being updated and added to the user record.

The extra table can only contain String, Number, and Boolean data types. You can update, add, and remove multiple keys in the extra table within a single update call.

--extra table
extra = {
  color = "Blue",
  age = 24,
  winner = true
}

To remove keys from the extra table you must pass a special constant core.NULL to the key.

--extra table
extra = {
  color = core.NULL, --remove the color key on update
  age = 24,
  winner = true
}

Returns

The updated users information as a table, or nil, error, and error code.

Example

--[[
Assuming the record already has an `extra` table like so:
{
  color = "Blue",
  age = 24,
  winner = true
}
--]]

--Update the user record
local res, err, errcode = core.users.update("aad3eba3...", {
  password = "superpass123",
  email = "me@town.com"
  extra = {
    color = "Red", --change color key
    high_score = 12300 --add high_score key
    age = core.NULL --remove age key
  }
})

--[[
The `extra` table for the record will now be:
{
  color = "Red",
  high_score = 12300,
  winner = true
}
--]]

delete

Remove a user from the Coronium user system. If you do not have a user_id, first use the users.getWithQuery method to get one.

core.users.delete(user_id)

Parameters

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

Returns

The records removed as a number (usually a 1), or nil, error, and error code.

Example

local res, err, code = core.users.delete("aad3eba3-9c9c-9a1b-f236de1e3752")

get

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

core.users.get(user_id)

OAuth Users

To get a user with an OAuth provider client ID, see the getWithProvider method in the OAuth API.

Example

local user, err, code = core.users.get("aad3eba3-9c9c-9a1b-f236de1e3752")

getGroup

Get a set of active user records based on group and application scope.

core.users.getGroup(scope, group, limit)

Parameters

Name	Description	Type	Required
scope	The application scope to be queried.	String	Y
group	The group name to search for.	String	Y
limit	Limit the records returned. See Limit below. Default is 100.	Number or Table	N

Active Users Only

This method only returns users that are marked as being active. See getWithQuery if you need users in a group regardless of active status.

Limit

To limit the rows returned, supply a number value to the limit parameter. To offset the limit, supply a table array of number values. For example, to return rows 6-15, then pass {5, 10}.

Returns

The records found as a table array, or nil, error, and error code. If limit is set to 1, then a single table with the user data is returned (not an array).

Example

local api = core.api()

function api.getUserGroup(input, scope)

  --use current scope from the client calling
  local users, err, code = core.users.getGroup(scope, "cadets", 10)

  --OR

  --provide your own scope as a string value
  local users, err, code = core.users.getGroup("Fun Run", "cadets", 10)

  ...
end

return api

getWithQuery

Get user record(s) based on specific query parameters.

core.users.getWithQuery(scope, query_params)

Parameters

Name	Description	Type	Required
scope	The application scope to be queried.	String	Y
query_tbl	A table with the query parameters (see below).	Table	N

Query Table Keys

Name	Description	Type	Required
active	The active state of the user.	Boolean	N
country_code	A two letter country identifier.	String	N
email	The users email address.	String	N
group	The group name to search within.	String	N
username	The users username.	String	N
orderby	The sorting attributes. See Orderby below.	Table	N
limit	Limit the records returned. See Limit below.	Number or Table	N

Important

String values are automatically run through mysql.escape. Do not double-escape values.

Orderby

The orderby key should be a table filled with column = direction pairs. The direction can be either "ASC" for ascending order or "DESC" for descending order. See example below.

Limit

To limit the rows returned, supply a number value to the limit key. To offset the limit, supply a table array of number values. For example, to return rows 6-15, then limit = {5, 10}.

Returns

The records found as a table array, or nil, error, and error code. If limit is set to 1, then a single table with the user data is returned (not an array). If no query parameters are provided, returns users in the supplied scope, with a default limit of 100.

Example

local users, err, code = core.users.getWithQuery("Space Race", {
  group = "cadets",
  active = true,
  orderby = { username = "ASC" },
  limit = 20
})

getAndMerge

Get a user record, and merge multiple associated database and table quries related to the user into the users record.

core.users.getAndMerge(user_id, merge_tbl)

Parameters

Name	Description	Type	Required
user_id	The users unique identifier.	String	Y
merge_tbl	A table array of database queries. See mysql.selectMerge	String	Y

Important

String values are automatically run through mysql.escape. Do not double-escape values.

Creating Associations

To use this method properly, you must create additonal databases with tables. The tables that you wish to associate to the user must have a user_id column filled with the users unique identifier. You can create the associations using the client-side or server-side MySQL module.

Returns

A user record with the associated queries included as the key name assigned in the query table. See mysql.selectMerge for more information on how the query entries work.

Errors

If the user is not found the method will return nil, error, and error code. If the user is found but any associated database queries fail, the user record will still be returned with any successful associated queries. On failed associations, the key property of the failed database query will contain an errors key describing the errors.

Example

local users, err, code = core.users.getAndMerge("aad3eba3...", {
  {
    db = "locations",
    tbl = "spots",
    columns = { "longitude", "latitude" },
    limit = 10,
    orderby = { longitude = "DESC" },
    key = "spots"
  }
})

sendConfirmationLink

Send an email to a newly registered user to confirm their email address. See also Confirmations.

core.users.sendConfirmationLink(user_id, options)

Mailgun Account Required

A valid Mailgun account is required to use this method. See the Mailgun Config section for more information.

Parameters

Name	Description	Type	Required
user_id	The users unique ID to send the confirmation link to.	String	Y
options	A table with email confirmation options (see below).	Table	Y

Confirmation Options Keys

Name	Description	Type	Required
from_email	The senders email address. This is usually your address.	String	Y
subject	The confirmation email subject line.	String	Y
email_tpl	Identifier for a custom confirmation email template.	String	N
tpl_keys	Additional template keys for the custom confirmation email template.	Table	N

Returns

A String indicating the sent state from Mailgun, can be "OK" or "Failed", or nil, error, and error code.

Note: If the user is not registered with an email address, this action will return an error.

Example

local res, err, code = core.users.sendConfirmationLink("0091633d...", {
  from_email = "code@develephant.com",
  subject = "Email confirmation"
})

See the Confirmations section for more detailed information.

sendPasswordResetLink

Send an email to a user with a special link to reset the users password. See also Password Reset.

core.users.sendPasswordResetLink(to_email, scope, options)

Mailgun Account Required

A valid Mailgun account is required to use this method. See the Mailgun Config section for more information.

Parameters

Name	Description	Type	Required
to_email	The users email address to send the reset link to.	String	Y
scope	The application scope to be queried.	String	Y
options	A table with email reset options (see below).	Table	Y

Reset Options Keys

Name	Description	Type	Required
from_email	The senders email address. This is usually your address.	String	Y
subject	The password reset email subject line.	String	Y
tpl_name	Identifier for a custom password reset email template.	String	N
tpl_keys	Additional template keys for the custom password reset email template.	Table	N

Returns

A boolean true value on success, or nil and an error.

Example

local res, err = core.users.sendPasswordResetLink("me@home.com", "Fun Run", 
  {
    from_email = "myapp@domain.com",
    subject = "Password Reset Request",     
  }
)

See the Password Reset section for more detailed information.