Neoclassical Philosophic Musings
Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »

uuid-apikey

1.4.6 • Public • Published

uuid-apikey

NPM

Actual version published on npm Travis build status Total npm module downloads Codacy Badge Codacy Badge

"API Keys are for people"

This module is a generator, validator, and converter that transforms UUIDs into human-readable Base32-Crockford encoded API Keys.

It turns this:

9b3ac4c9-0228-4e42-a244-927059b1a5ea

into this:

KCXC9JD-08M4WGH-M9294W1-B6RTBTH

Notes about Base32-Crockford API Keys

  • API Keys are 31 characters in length and consist of 4 groups of 7 characters separated by dashes (e.g. XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX)
  • API Keys are ideal for readable transports where they may be manually entered by a human and fonts may cause confusion.

For example, Base64 encoded values can be problematic when a human tried to type them in and Base32-Crockford API Keys avoid this by doing the following:

  • API Keys have no lower-case characters. The API Key parser handles all lower-case characters as their upper-case equivalent. (e.g. aA)
  • API Keys do not use tricky characters that can be confused in some fonts. The parser handled confusing characters as the same values.
    • the letters O, o, and the number 0
    • the letters L, l, I, i, and the number 1
  • API Keys do not use the letter U which could inadvertently lead to common English profanities.

Common Uses

  • Generating and using REST API Keys where a UUID is stored in a host DB but the API Key is shown to the user.
  • Generating APIKeys and storing the associated UUIDs for use as software license keys in software distribution.

NOTE: This package makes use of ES6 and ES7 functionality. If you are using a version of node prior to version 8 then you will need to use a polyfill (e.g. babel) for compatibility.

Installation

You can install uuid-apikey with NPM.

npm install uuid-apikey

Usage

const uuidAPIKey = require('uuid-apikey');
 
console.log(uuidAPIKey.create());

Output:

{ uuid: '0b9ca335-92a8-46d8-b477-eb2ed83ac927',
  apiKey: '1EEA6DC-JAM4DP2-PHVYPBN-V0XCJ9X' }

Command Line

uuid-apikey installs with a command line tool. The tool is available using the command apiKeyTool which can be install globally using:

  npm install uuid-apikey -g

Options

$ apiKeyTool.js
 
  Usage: apiKeyTool [options]
 
 
  Options:
 
    -V, --version          output the version number
    -g, --generate         Create a new API Key/UUID pair. Ignores other parameters if passed.
    -u, --uuid <uuid>      UUID for operation. If no other parameter is passed this is converted to an API Key.
    -a, --apikey <apikey>  API Key for operation. If no other parameter is passed this is converted to an UUID.
    -c, --check            Check the API Key and/or UUID provided are valid. If both API Key and UUID are passed then they are checked against each other.
    -h, --help             output usage information

Examples

Generation

$ apiKeyTool.js -g
 
  UUID(9b3ac4c9-0228-4e42-a244-927059b1a5ea)
APIKey(KCXC9JD-08M4WGH-M9294W1-B6RTBTH)

Conversion

$ apiKeyTool.js -a KCXC9JD-08M4WGH-M9294W1-B6RTBTH -u 9b3ac4c9-0228-4e42-a244-927059b1a5ea
 
UUID(9b3ac4c9-0228-4e42-a244-927059b1a5ea) => APIKey(KCXC9JD-08M4WGH-M9294W1-B6RTBTH)
APIKey(KCXC9JD-08M4WGH-M9294W1-B6RTBTH)    => UUID(9b3ac4c9-0228-4e42-a244-927059b1a5ea)

Testing

$ apiKeyTool.js -a KCXC9JD-08M4WGH-M9294W1-B6RTBTH -u 9b3ac4c9-0228-4e42-a244-927059b1a5ea -c
 
UUID(9b3ac4c9-0228-4e42-a244-927059b1a5ea) : valid
APIKey(KCXC9JD-08M4WGH-M9294W1-B6RTBTH)    : valid
UUID & APIKey are identical                : true

API Reference

.isUUID(uuid)

Tests if the UUID string passed is a valid UUID.

uuidAPIKey.isUUID('0b9ca335-92a8-46d8-b477-eb2ed83ac927');
uuidAPIKey.isUUID('NodeJS');

Output:

true
false

.isAPIKey(apiKey)

Tests if the API Key string passed is a valid API Key.

uuidAPIKey.isAPIKey('1EEA6DC-JAM4DP2-PHVYPBN-V0XCJ9X');
uuidAPIKey.isAPIKey('NodeJS');

Output:

true
false

.toAPIKey(uuid, [options])

Converts a valid UUID into an API Key. Throws a TypeError if the UUID is invalid.

uuidAPIKey.toAPIKey('0b9ca335-92a8-46d8-b477-eb2ed83ac927');
uuidAPIKey.toAPIKey('0b9ca335-92a8-46d8-b477-eb2ed83ac927', { 'noDashes': true });

Output:

'1EEA6DC-JAM4DP2-PHVYPBN-V0XCJ9X'
'1EEA6DCJAM4DP2PHVYPBNV0XCJ9X'

Options

Option Type Desc
noDashes boolean Generates an APIKey without dashes

.toUUID(apiKey)

Converts a valid API Key into an UUID. Throws a TypeError if the API Key is invalid.

uuidAPIKey.toUUID('1EEA6DC-JAM4DP2-PHVYPBN-V0XCJ9X');

Output:

'0b9ca335-92a8-46d8-b477-eb2ed83ac927'

.check(apiKey, uuid)

Test that an API Key and a UUID are identical. Throws a TypeError if either the API Key or the UUID is invalid.

uuidAPIKey.check('1EEA6DC-JAM4DP2-PHVYPBN-V0XCJ9X', '0b9ca335-92a8-46d8-b477-eb2ed83ac927');

Output:

true

.create([options])

Returns a new UUID and API Key pair

uuidAPIKey.create();

Output:

{ uuid: '0b9ca335-92a8-46d8-b477-eb2ed83ac927',
  apiKey: '1EEA6DC-JAM4DP2-PHVYPBN-V0XCJ9X' }

Options

Option Type Desc
noDashes boolean Generates an APIKey without dashes

License

Copyright (c) 2018,2019 Jay Reardon -- Licensed under the MIT license.

Install

npm i uuid-apikey

DownloadsWeekly Downloads

3,153

Version

1.4.6

License

MIT

Unpacked Size

28.8 kB

Total Files

11

Last publish

Collaborators

  • avatar