Registry / auth-security / prefixed-api-key

prefixed-api-key

JSON →
library1.1.1jsnpmunverified

The `prefixed-api-key` package, currently at version 1.1.1, provides a robust solution for generating 'Seam-style' API keys in JavaScript and TypeScript environments. These keys incorporate a user-defined prefix, a short token for identification and blocklisting, and a long token that is never stored directly, only its hash. This design enhances security by reducing the server's attack surface and enables features like GitHub secret scanning due to the predictable prefix format. The library leverages standard cryptographic practices, including Base58 encoding (RFC-compliant) for the token components, offering advantages such as shorter keys compared to hex/base32, double-click selection, and high entropy comparable to UUIDv4. It ships with TypeScript types and is suitable for both Node.js and browser environments, focusing on a secure and developer-friendly approach to API key management.

npm install prefixed-api-key
INSTALL
IMPORT
SIG · PREFIXED-API-KEY
P
prefixed-api-key
auth-securityjavascriptv1.1.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

generateAPIKey
import { generateAPIKey } from 'prefixed-api-key'
const { generateAPIKey } = require('prefixed-api-key')
Primary function for generating a complete API key object. Designed for ESM consumption.
checkAPIKey
import { checkAPIKey } from 'prefixed-api-key'
import checkAPIKey from 'prefixed-api-key'
Utility for validating an API key against its stored hash. It's a named export.
getTokenComponents
import { getTokenComponents } from 'prefixed-api-key'
const getTokenComponents = require('prefixed-api-key').getTokenComponents
Parses a full API key string into its prefix, short token, long token, and hash components. Named export.

Demonstrates how to generate a new Seam-style API key, highlighting which components to store securely and which to provide to the end-user, along with an example of safe storage.

import { generateAPIKey } from 'prefixed-api-key'; async function createAndStoreApiKey() { const key = await generateAPIKey({ keyPrefix: 'mycompany' // Required: a prefix for your keys }); // IMPORTANT: Store key.shortToken and key.longTokenHash in your database. // NEVER store key.longToken directly. Provide key.token to your customer. console.log('Generated Key Details:'); console.log(` Full API Key (for customer): ${key.token}`); console.log(` Short Token (for DB & display): ${key.shortToken}`); console.log(` Long Token Hash (for DB validation): ${key.longTokenHash}`); // console.log(` Long Token (secret, do not store): ${key.longToken}`); // Do NOT log or store this in production! // Example of storing in a mock database const mockDb = new Map(); mockDb.set(key.shortToken, { hash: key.longTokenHash, createdAt: new Date() }); console.log('\nStored in mock DB:'); console.log(mockDb.get(key.shortToken)); return key; } createAndStoreApiKey().catch(console.error);
Debug
Known issues
gotchaIt is critical for security to store only the `shortToken` and `longTokenHash` in your database. The `longToken` itself should *never* be stored on the server side to maintain the security benefits of hashed API keys. Provide only the full `token` string to your customers.
fix
Ensure your API key generation and storage logic explicitly saves `key.shortToken` and `key.longTokenHash`, and discards `key.longToken` after initial hashing and presentation to the user.
affects: >=1.0.0
gotchaThe `generateAPIKey` function is asynchronous and returns a Promise. Always use `await` when calling it to ensure the key is fully generated before proceeding, otherwise, you'll be working with a Promise object instead of the key details.
fix
Prefix calls to `generateAPIKey` with `await` within an `async` function, e.g., `const key = await generateAPIKey({ keyPrefix: 'your-app' });`
affects: >=1.0.0
gotchaWhen validating API keys, use the `checkAPIKey` function with the *full* API key string provided by the client and the *stored `longTokenHash`* from your database. Do not attempt to re-hash the client's provided key or use other comparison methods, as `checkAPIKey` handles the necessary extraction and comparison securely.
fix
Use `await checkAPIKey(fullKeyFromClient, storedLongTokenHash);` for all API key validation logic.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: generateAPIKey is not a function or TypeError: generateAPIKey(...).then is not a function
Attempting to use `generateAPIKey` in a CommonJS module without correctly importing it, or trying to use the function directly without `await` in an async context.
fix
For ESM, use `import { generateAPIKey } from 'prefixed-api-key';`. For CommonJS (if supported, though ESM is preferred), ensure the import path is correct and the `require` syntax is aligned with the package's export strategy (e.g., `const { generateAPIKey } = require('prefixed-api-key');` if it provides a CJS export, which might not be the case for modern ESM-first packages). Also, ensure `await` is used if calling in an `async` function.
Error: Invalid API Key Format
This error likely occurs when passing a malformed API key string to utility functions like `extractLongToken`, `extractShortToken`, `getTokenComponents`, or `checkAPIKey`. The functions expect the 'prefix_shorttoken_longtoken' format.
fix
Verify that the API key string passed to these utility functions strictly adheres to the 'prefix_shorttoken_longtoken' format generated by `prefixed-api-key`. Inspect the input string for typos, missing delimiters, or incorrect components.
Upgrade
Version history
1.1.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
21 hits · last 30 days
node
20
OpenAI (training)
1
Resources
prefixed-api-key — npm install prefixed-api-key · libregistry