uuid-apikey
"API Keys for people"
A generator, validator, and converter that transforms UUIDs into human-readable Base32-Crockford encoded API Keys.
- API Keys are 31 characters in length consisting of 4 groups of 7 characters separated by dashes (e.g. XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX)
- They avoids the problem that Base64 encoded values can create, such as:
- API Keys are entirely in upper-case, but treat lower-case values as their upper-case counterparts (e.g. a ≡ A)
- API Keys do not use tricky characters (i.e. the letter O, the letter L, and the letter I), but treat them equivalently with other characters they could be confused for (i.e. 0 ≡ O ≡ o / 1 ≡ L ≡ I ≡ l ≡ i )
- API Keys omit letters which could inadvertently lead to common profanities (i.e. the letter U)
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 probably 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.