fastify-auth-by-api-key

Fastify plugin for API key authentication via request headers.

Registers an onRequest hook that validates the API key on every request. Returns 401 for missing or invalid keys, 500 when your check function throws or returns Error status.

Compatible with Fastify 5.x.

Installation

npm install fastify-auth-by-api-key

Usage

Basic

import Fastify from 'fastify';
import { apiKeyPlugin, ApiKeyCheckStatus } from 'fastify-auth-by-api-key';

const VALID_KEYS = new Set(['secret-key-1', 'secret-key-2']);

const app = Fastify();
await app.register(apiKeyPlugin, {
  checkApiKey: (key) =>
    VALID_KEYS.has(key) ? ApiKeyCheckStatus.Valid : ApiKeyCheckStatus.Invalid,
});

app.get('/', async () => ({ ok: true }));
await app.listen({ port: 3000 });

Without a checkApiKey function every request is rejected with 401 — always provide one.

Async validation (e.g. database lookup)

await app.register(apiKeyPlugin, {
  checkApiKey: async (key) => {
    const found = await db.apiKeys.findOne({ key });
    if (!found) return ApiKeyCheckStatus.Invalid;
    if (found.revoked) return ApiKeyCheckStatus.Error;
    return ApiKeyCheckStatus.Valid;
  },
});

Custom header name

await app.register(apiKeyPlugin, {
  headerName: 'authorization',
  checkApiKey: (key) => { /* ... */ },
});

Query parameter fallback

await app.register(apiKeyPlugin, {
  allowAsQueryParameter: true,
  queryName: 'api_key',          // defaults to 'x-api-key'
  checkApiKey: (key) => { /* ... */ },
});
// GET /endpoint?api_key=secret-key-1

Header takes priority over query parameter when both are present.

Options

Option	Type	Default	Description
headerName	string	'x-api-key'	Request header to read the API key from. Case-insensitive.
allowInHeader	boolean	true	Accept the API key from the request header.
allowAsQueryParameter	boolean	false	Accept the API key as a query parameter.
queryName	string	'x-api-key'	Query parameter name to read the API key from.
checkApiKey	ApiKeyCheckFunction	() => Invalid	Function that validates the key and returns an ApiKeyCheckStatus.

API

apiKeyPlugin

A fastify-plugin-wrapped FastifyPluginAsync. Register it with fastify.register().

ApiKeyCheckStatus

enum ApiKeyCheckStatus {
  Valid   = 'valid',    // key accepted → request proceeds
  Invalid = 'invalid',  // key rejected → 401 Unauthorized
  Error   = 'error',    // check failed → 500 Internal Server Error
}

ApiKeyCheckFunction

type ApiKeyCheckFunction = (
  apiKey: string,
) => ApiKeyCheckStatus | Promise<ApiKeyCheckStatus>;

ApiKeyPluginOptions

interface ApiKeyPluginOptions {
  checkApiKey?: ApiKeyCheckFunction;
  headerName?: string;
  allowInHeader?: boolean;
  allowAsQueryParameter?: boolean;
  queryName?: string;
}

License

ISC