Quick Start
Start using UsefulKey in minutes. Configure adapters, add plugins, and see how each plugin changes the UsefulKey API.
Install
npm i usefulkeyQuick Start
Initialize UsefulKey
Configure adapters and defaults. Use in-memory adapters to get started quickly. See Configuration for more options.
import { usefulkey, MemoryKeyStore, MemoryRateLimitStore, ConsoleAnalytics } from "usefulkey";
const uk = usefulkey(
{
adapters: {
keyStore: new MemoryKeyStore(),
rateLimitStore: new MemoryRateLimitStore(),
analytics: new ConsoleAnalytics(),
},
});Add plugins
Plugins add behavior and may extend the UsefulKey instance with new methods.
const uk = usefulkey(
{
// ...config
},
{
plugins: [
//All plugins are optional.
// Enable/disable keys
// enableDisablePlugin(),
// IP access control with a static allow list
// ipAccessControlStatic({ allow: ["1.1.1.1"] }),
// IP access control with a memory allow list that can be modified at runtime
// ipAccessControlMemory(),
// IP access control with persistent allow/deny in your KeyStore
// ipAccessControlKeystore(),
// Permissions/scopes
// permissionsScopesPlugin({ metadataKey: "scopes" }),
// Rate limit default for all verifyKey calls
// ratelimit({ default: { kind: "fixed", limit: 100, duration: "1m" } }),
// Usage limits per key
// usageLimitsPerKeyPlugin(),
],
}
);Basic create and verify
Use the UsefulKey instance to create and verify keys.
// Create a key
const { result: created } = await uk.createKey({ metadata: { plan: "free" } });
// created -> { id: "...", key: "...", metadata: { plan: "free" } }
// Verify the key (namespace required when ratelimit plugin is enabled)
const { result: verified } = await uk.verifyKey({
key: created.key,
namespace: "api"
});
// verified -> { valid: true, keyId: "...", metadata: { plan: "free" } }
// Get the key record (doesn't include plaintext key)
const { result: keyRecord } = await uk.getKey(created.key);
// keyRecord -> {
// id: "...",
// userId: null,
// prefix: "...",
// keyHash: "...",
// createdAt: 1234567890,
// expiresAt: null,
// metadata: { plan: "free" },
// usesRemaining: null,
// revokedAt: null
// }Optionally wait for setup
Some plugins/adapters perform async setup. You can await readiness once during boot.
await uk.ready;See how plugins and adapters work in the Concepts section.
For more, see the API Reference and individual plugin pages under Plugins.