Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Flexkey is a Ruby gem for generating unique, random strings for use as product keys, redemption codes, invoice numbers, passwords, etc.


Add this line to your application's Gemfile:

gem 'flexkey'

And then execute:

$ bundle

Or install it yourself as:

$ gem install flexkey

None. Flexkey has been tested with Ruby 1.9.3 and 2.0.


Basic usage

Instantiate a new generator with and provide a format and char_pool. Then, generate a single key or multiple unique keys with the generate method:

keygen = 'aaaa-aa', char_pool: { 'a' => :alpha_upper })
# => #<Flexkey::Generator @format="aaaa-aa", @char_pool={"a"=>:alpha_upper}, @n_possible_keys=308915776>
# => "KBND-NR"
# => ["IVXT-LB", "BFZB-LM", "WIVG-ZJ"]

In this example, Flexkey generates a key by replacing each instance of 'a' in the string 'aaaa-aa' with a character randomly drawn from a pool of uppercase letters while leaving unspecified characters (i.e. '-') alone.

Since you're most likely persisting generated keys in a database, even though generate(n) will return n unique keys, you'll still want to validate them for uniqueness against keys you've previously saved.

Built-in character types
Character type Description
alpha_upper uppercase letters
alpha_lower lowercase letters
numeric numerals
alpha_upper_clear alpha_upper without ambiguous letters ("S", "O", etc.)
alpha_lower_clear alpha_lower without ambiguous letters ("l", "O", etc.)
numeric_clear numeric without ambiguous numerals ("0", "1", and "5")
symbol symbols on a standard U.S. keyboard
basic_symbol basic symbols on a standard U.S. keyboard

The names and characters present in each type can be retrieved as such:

# => [:alpha_upper, :alpha_lower, :numeric, :alpha_upper_clear, :alpha_lower_clear, :numeric_clear, :symbol, :basic_symbol]
# => {:alpha_upper=>"ABCDEFGHIJKLMNOPQRSTUVWXYZ", :alpha_lower=>"abcdefghijklmnopqrstuvwxyz", :numeric=>"0123456789", :alpha_upper_clear=>"ABCDEFGHJKLMNPQRTUVWXYZ", :alpha_lower_clear=>"abcdefghjkmnpqrtuvwxyz", :numeric_clear=>"2346789", :symbol=>"!@\#$%^&*;:()_+-=[]{}\\|'\",.<>/?", :basic_symbol=>"!@\#$%^&*;:"}
Examples 'a-nnnn', char_pool: {
  'a' => :alpha_upper, 'n' => :numeric
# => "Y-1145" 'SN-nnnnnnnnn', char_pool: {
  'n' => :numeric
# => "SN-181073470" '', char_pool: {
  'A' => :alpha_upper_clear, 'a' => :alpha_lower_clear, 'n' => :numeric_clear, 's' => :basic_symbol
# => "*:"

You can also specify a custom string instead of using a built-in type. 'annn/c', char_pool: {
  'a' => :alpha_upper, 'n' => :numeric, 'c' => 'LMN'
# => ["X905/N", "F865/L", "M423/N", "V564/L", "V874/M"] 'mnnnnnnn', char_pool: {
  'm' => '123456789', 'n' => :numeric
# => ["45862188", "23054329", "36248220", "56044911", "49873464"]
Selecting from multiple character types

To replace a character in the format from a pool of multiple character types, specify the both the types and proportions in the char_pool. For example, to generate keys of length 10 where each character is randomly selected from a pool of uppercase letters and numerals with equal proportions, do the following: '..........', char_pool: {
  '.' => { alpha_upper: 0.5, numeric: 0.5 }
# => ["OXAEXC2O87", "3D95JXQ60P", "8F28OX31Y8", "65ZY7IM6TL", "B971Q602SO"]

You can specify proportions with any positive numbers: 'U-ccccc-ccccc', char_pool: {
  'U' => :alpha_upper_clear, 'c' => { numeric_clear: 1, alpha_upper_clear: 7 }
# => ["H-KYLYK-DQLK3", "U-7QUXV-6DXNW", "X-REYAX-LL489", "L-8ABNJ-ZW3A7", "M-TPVTW-VEMTE"] 'UUUUU.LLLLL', char_pool: {
  'U' => { 'WXYZ' => 3, 'FGH' => 1 }, 'L' => :alpha_lower_clear
# => ["XZYYF.kwkth", "HHFYW.nkpdr", "WXXGW.fvyeu", "HWFXW.xzgeq", "WXWXW.twrdk"]
Number of possible keys

Flexkey will raise an exception if you try to request more keys than are possible with the format you provided:

keygen = 'annn', char_pool: {
  'a' => :alpha_upper, 'n' => :numeric
# => ["F202", "U811", "W802"]
# Flexkey::GeneratorError: There are only 26000 possible keys
# => 26000

The instance method n_possible_keys is available for reference as seen above.

Since generate(n) works by building an array of randomly-generated keys while checking new keys for uniqueness, it's not a good choice for generating all possible keys for a particular format. In that case, it makes more sense to simply build your list of keys iteratively.


If you're only interested in using the proportional sampling feature of Flexkey and will generate keys yourself, use Flexkey::CharPool.generate with a single hash argument:

char_pool = Flexkey::CharPool.generate({ alpha_upper: 0.75, numeric: 0.25 }) { char_pool.sample }.join

Additional documentation

At Rubydocs.


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request


No description, website, or topics provided.




No packages published


You can’t perform that action at this time.