# nestjs-api-keys

> A NestJS utility that allows API keys based security

Latest version **1.1.8** (published 2025-05-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install nestjs-api-keys
pnpm add nestjs-api-keys
yarn add nestjs-api-keys
bun add nestjs-api-keys
```

## Health

**Score 45/100 (D)** — status: stable.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 1.1.8 |
| Published | 2025-05-06 |
| First published | 2023-11-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 22.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | TheMineWay |
| Maintainers | themineway |

## Links

- npm: https://www.npmjs.com/package/nestjs-api-keys
- Repository: https://github.com/TheMineWay/nestjs-api-keys
- Homepage: https://github.com/TheMineWay/nestjs-api-keys#readme
- Issues: https://github.com/TheMineWay/nestjs-api-keys/issues
- npm.io page: https://npm.io/package/nestjs-api-keys

## Dependencies (2)

- [@types/node](https://npm.io/package/@types/node.md) ^22.7.4
- [@nestjs/common](https://npm.io/package/@nestjs/common.md) ^11.0.10

## Recent versions

- 1.1.8 (latest) — 2025-05-06
- 1.1.7 — 2025-03-14
- 1.1.6 — 2024-11-26
- 1.1.5 — 2024-11-18
- 1.1.4 — 2024-11-11
- 1.1.3 — 2024-10-28
- 1.1.2 — 2024-10-24
- 1.1.1 — 2024-09-30
- 1.1.0 — 2023-11-03
- 1.0.2 — 2023-11-01
- 1.0.1 — 2023-11-01
- 1.0.0 — 2023-11-01

## README

# NestJS API Keys

[![Node.js Package](https://github.com/TheMineWay/nestjs-api-keys/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/TheMineWay/nestjs-api-keys/actions/workflows/npm-publish.yml)

A NestJS API keys utility which allows you to secure APIs using an API Key based system.

This library only works in APIs made with NestJS.

## 0. Installing

Install the package using:

```bash
npm i nestjs-api-keys
```

or

```bash
yarn add nestjs-api-keys
```

## 1. Setup

First, you need to register the **ApiKeysModule**. You can do that by going to your **AppModule** and calling the **register** static method of the **ApiKeysModule** class:

```ts
@Module({
  imports: [
    ApiKeysModule.register({
      apiKeys: [],
    }),
  ],
})
export class AppModule {}
```

In the **apiKeys** array you need to provide all available _API Keys_.

```ts
ApiKeysModule.register({
    apiKeys: [
        {
            name: 'For reading users',   // Descriptive name
            keys: ['supersecretapikey'], // API keys composing this key
            permissions: ['users.read'], // Permissions given to this key
        },
    ],
}),
```

- **name:** allows you to provide a name to the API key for identification purposes (there is no functionality attached to the name).
- **keys:** an array where you provide all keys that compose the API key. Having more than one Key allows you to switch keys without downtime.
- **permissions:** an array where you place permissions as strings. Endpoints and controllers can require permissions, so you can assign them to api keys in here.

**REMEMBER: it is recommended that you DON'T provide directly here these values in production. You should get keys from a _.ENV_ file or any other secure source.**

In production you should (for example):

```ts
ApiKeysModule.register({
    apiKeys: JSON.parse(process.env.API_KEYS_JSON_STRING),
}),
```

### 1.0. Extra options

- **apiKeyHeader:** allows you to change the header name where **API key** is read. By default it is 'api-key'.

## 2. Protecting endpoints

You can secure any endpoint by using the **ApiKeyGuard** guard:

```ts
@UseGuards(
    ApiKeyGuard({
        permissions: ['users.read'],
    }),
)
@Get('users')
async getUsers() {
    // Fetch users
}
```

---
_Source: https://npm.io/package/nestjs-api-keys · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._