The tulip.pkg.token module exports the token package.


  • tulip.pkg.database


  • allowed_types: array of string = if set, only those types will be allowed for the tokens.

#API Extensions

Registering this package provides the following method and field extensions.

#v, err = App:token(t[, conn[, tok]])

Generates a one-time secret token, validates such a token, or deletes token(s).

If the generated token has 'once' set, then when it is validated, its type and ref_id must match, and it must not be expired. If it does not have 'once' set, then when validated only its type must match, and it must not be expired. The ref_id value is returned as second value when the token is valid (if the first returned value is true). This is because the not-once tokens are typically used to associate a token with an id (e.g. session tokens), while once tokens are used for extra validation so the ref_id must be provided and must be associated with that token (e.g. reset password, change email address tokens, where the relevant user ID is known).


  • t: table = a table with the following fields:
    • t.type: string = the type of the token (e.g. resetpwd)
    • t.ref_id: number = the reference id of the token (e.g. user id)
    • t.max_age: number = number of seconds before token expires
    • t.once: boolean|nil = if true, generate a single-use token that is deleted when validated. Otherwise the token stays alive until expired (e.g. a session id token).
    • t.delete: boolean|nil = if true, deletes the token upon validation, even if it is not a single-use token (e.g. for logout behaviour). If no tok value is provided and delete is true, deletes all tokens associated with type and ref_id (without validation).
  • conn: connection = optional database connection to use
  • tok: string = if provided, validates that token, otherwise generate a new token.


  • v: boolean|string = if tok is provided, returns a boolean that indicates if the token is valid, otherwise returns a string that is the base64-encoded generated token. Is nil on error or invalid token. If it returns true, returns the associated ref_id as second value.
  • err: Error|number|nil = error message if v is falsy, the ref_id if v is true.

Back to index

About this wiki

commit 3ebfbd288b8e5c95fdf8ce2027a0e94cfa1c8976
Author: Martin Angers <martin.n.angers@gmail.com>
Date:   2021-02-25T14:07:12-05:00

Update to reflect Request:validate_body
Clone this wiki
https://git.sr.ht/~mna/tulip-wiki (read-only)
git@git.sr.ht:~mna/tulip-wiki (read/write)