@playstack/nest-api-keys

NestJS metadata, dependency injection, and request guarding for Playstack API keys.

Free. MIT licensed. Check preview availability before installing. See package access.

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

Install

After confirming preview access, install the package at your application's shared Playstack version:

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

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

Install and compose

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.

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. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.