Input lists

Locksmith uses input lists for managed sets of bulk inputs – pieces of data that a visitor must supply in order to gain access. They're useful when you have more than just a few inputs – perhaps you need to allow a set of 500,000 passcodes, for example, or a few thousand random secret links.

Input lists are synchronized from external sources, configured with a URL pointing to a data source – this could be a text file on your own server, a Google Sheets document, an Excel file on Google Drive, or even a JSON array provided by a Mechanic cache endpoint. Synchronizing with an external source allows you to manage this bulk data however you like, without being constrained to Locksmith's own data management.

Configuration

Input lists are configured in your Locksmith account settings. To find this area, open Locksmith's home screen, then scroll to the end of the page, and click the "View all settings" button. Input lists are available in the "Advanced" area.

Options

An input list has three options:

  • Name
  • Source URL (must be either unauthenticated, or must be a Google Drive file or Sheets document that has been shared with input-lists@locksmith-app.iam.gserviceaccount.com)
  • Input values are case-sensitive (enable to require an exact case match)

Supported file formats

Source files may be of the following formats:

  • TXT (one input value per line)
  • CSV (a single column of input values, one value per row)
  • JSON (an array of strings)
  • Google Sheets (a document having a single column of input values, one value per row)
  • Microsoft Excel XLSX (a spreadsheet having a single column of input values, one per row)

Syncing

When an input list is synchronized with its source, any new items found in the source file will be added to Locksmith's copy of the list. Any items that are  no longer found in the source file will be removed from Locksmith's copy of the list.

Input lists that are sourced from Google Drive will be automatically synchronized whenever the source file is changed. (When used with Google Sheets, this allows for interesting flexibility: one could use a Google Form that saves data to a Google Sheets file, which then feeds into an input list. Whenever the form is submitted, Locksmith would automatically sync a new value into the input list.)

All other input lists are automatically synchronized on a regular basis (currently at midnight UTC, subject to change without notice).

All input lists may be synchronized manually, by using the "Sync input list" button for the respective list.

Usage with specific key conditions

Once at least one input list has created, you may use it when configuring a new key condition in your lock settings, by choosing one of the "Permit if..." options that mentions input lists.

Passcodes

When configuring your key condition, select the "Permit if the customer gives a passcode from an input list…" option to have Locksmith compare customer input with items in your input list.

As with Locksmith's other passcode conditions, you may configure this condition to "remember" returning customers who are logged in. If this option is enabled, Locksmith will compare previously-accepted passcodes from the customer's records with current items in the selected input list. This means that removing previously-used items from the input list will result in the relevant returning customers being "forgotten".

Secret links

When configuring your key condition, select the "Permit if the customer arrives using a secret link code from an input list…" option to match the visitor's current URL with items in your input list. As with standard secret link keys, Locksmith will be trying to find matching secret link codes in the following parts of the URL:

  • The URL's "search" portion. For example, in a URL that looks like "https://example.com/?foo=bar&baz&ls=qux", Locksmith will consider items in your input list having the value "foo=bar&baz&ls=qux".
  • Any component in the URL's "search" portion. For example, in a URL that looks like "https://example.com/?foo=bar&baz&qux", Locksmith will consider items in your input list having one of these values: "foo=bar", "baz", "ls=qux".
  • The "ls" query parameter, if present. For example, in a URL that looks like "https://example.com/?foo=bar&baz&ls=qux", Locksmith will consider items in your input list having the value "qux".

This means that you may form your shared URLs in any of the following ways, using an example secret link code of "foobar" to illustrate:

Feel free to combine either option with other query parameters, like so:

As with Locksmith's other secret link condition, you may configure this condition to "remember" returning customers who are logged in. If this option is enabled, Locksmith will compare previously-accepted secret link codes from the customer's records with  current items in the selected input list. This means that removing previously-used items from the input list will result in the relevant returning customers being "forgotten".

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.