---
title: "@playstack/nest-api-keys"
description: "NestJS metadata, dependency injection, and request guarding for Playstack API keys."
tags: ["package","identity","api-keys","nestjs","free"]
---

{/* package-access:start */}

> **Free.** MIT licensed. Check preview availability before installing. See [package access](/docs/packages#access-policy).

{/* package-access:end */}

`@playstack/nest-api-keys` translates API-key verification, scope requirements, and atomic rate limits into explicit NestJS route declarations.

{/* package-install:start */}

## Install

After confirming [preview access](/docs/packages#access-policy), install the package at your application's shared Playstack version:

```sh
npm install --save-exact @playstack/nest-api-keys@0.1.0-beta.1
```

Check the peer requirements below before choosing a runtime or provider.

{/* package-install:end */}

## Install and compose

```ts
PlaystackApiKeysModule.forRoot({
  apiKeys,
  limiter,
  rateLimitName: 'api-keys.request',
  resolveAccountId: (key) => key.owner.id,
})

@UseGuards(PlaystackApiKeysGuard)
@RequireApiKey('spans:write')
@Post('/spans')
ingest(@Req() request: ApiKeyRequest) {
  return service.ingest(request.apiKey!)
}
```

## Configuration reference

| `NestApiKeysOptions` property | Required | Purpose |
| --- | --- | --- |
| `apiKeys` | Yes | Structural verifier exposing `verify({ secret, requiredScopes })`. |
| `limiter` | Yes | Consumes the API-key and account buckets atomically. |
| `rateLimitName` | Yes | Configured shared rate-limit policy name. |
| `headerName` | No | Credential header; defaults to Authorization Bearer. |
| `resolveAccountId` | Yes | Maps the verified key and request to the authoritative account bucket ID. |

The guard reads the credential, passes `@RequireApiKey` scopes to verification, resolves account context, and calls the limiter once with `{ apiKey, account }` subjects plus the key’s optional capacity override. Storage failure returns 503; a denied bucket returns 429. The verified record is attached as `request.apiKey`.

Use `forRootAsync({ imports, inject, useFactory })` for DI-based configuration.

## Boundary

The adapter does not issue keys, own persistence, infer account tenancy, or install a global guard. Provider-specific clients and application authorization remain accessible through the supplied callbacks and services.

{/* package-reference:start */}

## API entry points and requirements

Reference snapshot: `@playstack/nest-api-keys@0.1.0-beta.1`. Import only the entry point your runtime needs. Paths below are relative to the installed package; use **Go to Definition** in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

| Public entry point | Declaration file |
| --- | --- |
| `@playstack/nest-api-keys` | `./dist/index.d.ts` |
| `@playstack/nest-api-keys/package.json` | No TypeScript declaration (asset or metadata export). |

Node.js engine requirement: `>=20`. This is not a claim that every entry point works in browsers or Workers.

### Peer dependencies

Keep existing framework versions that satisfy these ranges. Install optional peers only when using the corresponding adapter. The package manager resolves ordinary dependencies separately.

| Peer | Compatible range | When needed |
| --- | --- | --- |
| `@nestjs/common` | `^10.0.0 \|\| ^11.0.0` | Required by the package. |
| `@nestjs/core` | `^10.0.0 \|\| ^11.0.0` | Required by the package. |
| `@playstack/api-keys` | `0.1.0-beta.1` | Required by the package. |
| `@playstack/rate-limit` | `0.1.0-beta.1` | Required by the package. |
| `reflect-metadata` | `^0.1.13 \|\| ^0.2.0` | Required by the package. |
| `rxjs` | `^7.0.0` | Required by the package. |

For a complete first program, start with [Getting started](/docs/getting-started). For API lookup and partial-example conventions, see [Reading the reference](/docs/packages#reading-the-reference). Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.

{/* package-reference:end */}