{"id":13456558,"url":"https://github.com/chronosis/uuid-apikey","last_synced_at":"2025-04-24T09:31:34.196Z","repository":{"id":22321576,"uuid":"95934296","full_name":"chronosis/uuid-apikey","owner":"chronosis","description":"A Base32-Crockford encoded API Key generator and converter to turn UUIDs into human readable API Keys","archived":false,"fork":false,"pushed_at":"2023-01-16T09:02:28.000Z","size":1086,"stargazers_count":58,"open_issues_count":15,"forks_count":13,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-14T08:32:16.598Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chronosis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-07-01T01:14:32.000Z","updated_at":"2024-02-19T02:39:09.000Z","dependencies_parsed_at":"2023-01-13T21:57:29.559Z","dependency_job_id":null,"html_url":"https://github.com/chronosis/uuid-apikey","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chronosis%2Fuuid-apikey","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chronosis%2Fuuid-apikey/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chronosis%2Fuuid-apikey/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chronosis%2Fuuid-apikey/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chronosis","download_url":"https://codeload.github.com/chronosis/uuid-apikey/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250600704,"owners_count":21457012,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T08:01:24.040Z","updated_at":"2025-04-24T09:31:33.881Z","avatar_url":"https://github.com/chronosis.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# uuid-apikey\n\n[![NPM](https://nodei.co/npm/uuid-apikey.png?downloads=true)](https://nodei.co/npm/uuid-apikey/)\n\n[![Actual version published on npm](http://img.shields.io/npm/v/uuid-apikey.svg)](https://www.npmjs.org/package/uuid-apikey)\n[![Actions Status](https://github.com/chronosis/uuid-apikey/workflows/Build%20and%20Test%20Master/badge.svg)](https://github.com/chronosis/uuid-apikey/workflows/actions)\n[![Total npm module downloads](http://img.shields.io/npm/dt/uuid-apikey.svg)](https://www.npmjs.org/package/uuid-apikey)\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/6c4ea28976c54c0493f8c0a4e742a95a)](https://www.codacy.com/app/chronosis/uuid-apikey?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=chronosis/uuid-apikey\u0026amp;utm_campaign=Badge_Grade)\n[![Codacy Badge](https://api.codacy.com/project/badge/Coverage/6c4ea28976c54c0493f8c0a4e742a95a)](https://www.codacy.com/app/chronosis/uuid-apikey?utm_source=github.com\u0026utm_medium=referral\u0026utm_content=chronosis/uuid-apikey\u0026utm_campaign=Badge_Coverage)\n\n*\"API Keys are for people\"*\n\nThis module is a generator, validator, and converter that transforms UUIDs into human-readable Base32-Crockford encoded API Keys.\n\nIt turns this:\n```\n9b3ac4c9-0228-4e42-a244-927059b1a5ea\n```\ninto this:\n```\nKCXC9JD-08M4WGH-M9294W1-B6RTBTH\n```\n\n## Notes about Base32-Crockford API Keys\n * API Keys are 31 characters in length and consist of 4 groups of 7 characters separated by dashes *(e.g. XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX)*\n * API Keys are ideal for readable transports where they may be manually entered by a human and similarty character glyphs within the printed typeface may cause confusion. \"Is that an O or a 0?\"\n\nBase32-Crockford API Keys it avoids these problems by doing the following:\n   * API Keys have no lower-case characters. The API Key parser handles all lower-case characters as their upper-case equivalent. *(e.g. `a` ≡ `A`)*\n   * API Keys do not use similar characters glyphs which can be confused in some typefaces. The parser handles confusing characters as the same values.  \n     * the letters `O`, `o`, and the number `0`\n     * the letters `L`, `l`, `I`, `i`, and the number `1`\n   * API Keys do not use the letter `U` which could inadvertently lead to common English profanities.\n\n## Common Uses\n * Generating and using REST API Keys where a UUID is stored in a host DB but the API Key is shown to the user.\n * Generating APIKeys and storing the associated equivalent UUIDs values for use as software license keys in software distribution.\n\n***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.\n\n## Installation\nYou can install `uuid-apikey` with NPM.\n```shell\nnpm install uuid-apikey\n```\n## Usage\n```es2016\nconst uuidAPIKey = require('uuid-apikey');\n\nconsole.log(uuidAPIKey.create());\n```\n**Output**:\n```\n{ uuid: '0b9ca335-92a8-46d8-b477-eb2ed83ac927',\n  apiKey: '1EEA6DC-JAM4DP2-PHVYPBN-V0XCJ9X' }\n```\n\n## Command Line\n`uuid-apikey` installs with a command line tool. The tool is available using the command `apiKeyTool` which can be install globally using:\n\n```\n  npm install uuid-apikey -g\n```\n\n### Options\n```shell\n$ apiKeyTool.js\n\n  Usage: apiKeyTool [options]\n\n\n  Options:\n\n    -V, --version          output the version number\n    -g, --generate         Create a new API Key/UUID pair. Ignores other parameters if passed.\n    -u, --uuid \u003cuuid\u003e      UUID for operation. If no other parameter is passed this is converted to an API Key.\n    -a, --apikey \u003capikey\u003e  API Key for operation. If no other parameter is passed this is converted to an UUID.\n    -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.\n    -h, --help             output usage information\n```\n\n### Examples\n#### Generation\n```shell\n$ apiKeyTool.js -g\n\n  UUID(9b3ac4c9-0228-4e42-a244-927059b1a5ea)\nAPIKey(KCXC9JD-08M4WGH-M9294W1-B6RTBTH)\n```\n#### Conversion\n```shell\n$ apiKeyTool.js -a KCXC9JD-08M4WGH-M9294W1-B6RTBTH -u 9b3ac4c9-0228-4e42-a244-927059b1a5ea\n\nUUID(9b3ac4c9-0228-4e42-a244-927059b1a5ea) =\u003e APIKey(KCXC9JD-08M4WGH-M9294W1-B6RTBTH)\nAPIKey(KCXC9JD-08M4WGH-M9294W1-B6RTBTH)    =\u003e UUID(9b3ac4c9-0228-4e42-a244-927059b1a5ea)\n```\n\n#### Testing\n```shell\n$ apiKeyTool.js -a KCXC9JD-08M4WGH-M9294W1-B6RTBTH -u 9b3ac4c9-0228-4e42-a244-927059b1a5ea -c\n\nUUID(9b3ac4c9-0228-4e42-a244-927059b1a5ea) : valid\nAPIKey(KCXC9JD-08M4WGH-M9294W1-B6RTBTH)    : valid\nUUID \u0026 APIKey are identical                : true\n```\n\n## API Reference\n\n### .isUUID(uuid)\nTests if the UUID string passed is a valid UUID.\n```es2016\nuuidAPIKey.isUUID('0b9ca335-92a8-46d8-b477-eb2ed83ac927');\nuuidAPIKey.isUUID('NodeJS');\n```\n**Output**:\n```\ntrue\nfalse\n```\n\n### .isAPIKey(apiKey)\nTests if the API Key string passed is a valid API Key.\n```es2016\nuuidAPIKey.isAPIKey('1EEA6DC-JAM4DP2-PHVYPBN-V0XCJ9X');\nuuidAPIKey.isAPIKey('NodeJS');\n```\n**Output**:\n```\ntrue\nfalse\n```\n\n### .toAPIKey(uuid, [options])\nConverts a valid UUID into an API Key. Throws a `TypeError` if the UUID is invalid.\n```es2016\nuuidAPIKey.toAPIKey('0b9ca335-92a8-46d8-b477-eb2ed83ac927');\nuuidAPIKey.toAPIKey('0b9ca335-92a8-46d8-b477-eb2ed83ac927', { 'noDashes': true });\n```\n**Output**:\n```\n'1EEA6DC-JAM4DP2-PHVYPBN-V0XCJ9X'\n'1EEA6DCJAM4DP2PHVYPBNV0XCJ9X'\n```\n**Options**\n\n| Option | Type | Desc |\n| ------ | ---- | ---- |\n| noDashes | boolean | Generates an APIKey without dashes |\n\n### .toUUID(apiKey)\nConverts a valid API Key into an UUID. Throws a `TypeError` if the API Key is invalid.\n```es2016\nuuidAPIKey.toUUID('1EEA6DC-JAM4DP2-PHVYPBN-V0XCJ9X');\n```\n**Output**:\n```\n'0b9ca335-92a8-46d8-b477-eb2ed83ac927'\n```\n\n### .check(apiKey, uuid)\nTest that an API Key and a UUID are identical. Throws a `TypeError` if either the API Key or the UUID is invalid.\n```es2016\nuuidAPIKey.check('1EEA6DC-JAM4DP2-PHVYPBN-V0XCJ9X', '0b9ca335-92a8-46d8-b477-eb2ed83ac927');\n```\n**Output**:\n```\ntrue\n```\n\n### .create([options])\nReturns a new UUID and API Key pair\n```es2016\nuuidAPIKey.create();\n```\n**Output**:\n```\n{ uuid: '0b9ca335-92a8-46d8-b477-eb2ed83ac927',\n  apiKey: '1EEA6DC-JAM4DP2-PHVYPBN-V0XCJ9X' }\n```\n**Options**\n\n| Option | Type | Desc |\n| ------ | ---- | ---- |\n| noDashes | boolean | Generates an APIKey without dashes |\n\n## License\nCopyright (c) 2018,2019 Jay Reardon -- Licensed under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchronosis%2Fuuid-apikey","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchronosis%2Fuuid-apikey","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchronosis%2Fuuid-apikey/lists"}