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