Registry / aws / serverless-add-api-key

serverless-add-api-key

library4.2.1jsnpmunverified

The `serverless-add-api-key` plugin extends the Serverless Framework to provide enhanced management of AWS API Gateway API keys and usage plans. Unlike native Serverless functionality, this plugin allows associating multiple services with the same API key and usage plan, facilitating consistent authentication across microservices. It automatically creates API keys and usage plans if they don't exist and supports associating existing keys. The current stable version is 4.2.1, with releases typically following major Serverless Framework updates or when new features for API Gateway integration are required. Key differentiators include its ability to reuse existing keys, support for multiple keys per service, and advanced configuration options for usage plans, including quotas and throttling. It also provides secure handling of API key values through KMS encryption, preventing raw keys from being exposed in repositories.

aws devops

npm install serverless-add-api-key

github ↗package ↗

INSTALL

IMPORT

SIG · SERVERLESS-ADD-API

serverless-add-api-key

awsjavascriptv4.2.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

plugin entry

✓ plugins: - serverless-add-api-key

✗ require('serverless-add-api-key')

Serverless plugins are loaded via the `plugins` array in `serverless.yml`, not directly imported in JavaScript/TypeScript code.

API Key configuration

✓ custom: apiKeys: - name: MyServiceKey value: ${ssm:/aws/reference/secretsmanager/my-api-secret~partial} usagePlan: name: MyUsagePlan throttle: rateLimit: 10 burstLimit: 20

✗ apiKeys: - name: MyServiceKey

Configuration for the plugin resides under the `custom.apiKeys` section in `serverless.yml`. Ensure correct YAML indentation and structure.

KMS encrypted value

✓ custom: apiKeys: - name: SecureKey value: encrypted: A-KMS-Encrypted-Value kmsKeyRegion: us-east-1

✗ value: 'AQICAH...'

For KMS-encrypted values, the `value` property must be an object with `encrypted` and optionally `kmsKeyRegion` keys. Raw encrypted strings will not be decrypted.

This quickstart demonstrates how to configure `serverless-add-api-key` to create multiple API keys, including one with a custom usage plan, one with a KMS-encrypted value, and another that defaults to the provider-level usage plan. It shows how to integrate keys with HTTP API Gateway endpoints and use stage-specific naming.

service: my-serverless-api provider: name: aws runtime: nodejs18.x stage: dev region: us-east-1 usagePlan: name: default-api-usage-plan description: Default plan for my-serverless-api throttle: rateLimit: 10 burstLimit: 5 quota: limit: 1000 period: DAY plugins: - serverless-add-api-key custom: apiKeys: - name: MyServiceGlobalKey-${sls:stage} value: ${env:MY_API_KEY_VALUE, 'default-secure-key-1234567890'} usagePlan: name: CustomUsagePlanForGlobalKey-${sls:stage} description: Usage plan specific to the global key for this stage throttle: rateLimit: 20 burstLimit: 10 quota: limit: 5000 period: MONTH - name: MyEncryptedKey-${sls:stage} value: encrypted: AQICAHinIKhx8yV+y97+qS5naGEBUQrTP8RPE4HDnVvd0AzJ/wGF2tC0dPMHO... # Replace with actual KMS encrypted value kmsKeyRegion: us-east-1 # Specify the region where the KMS key is located - name: AnotherServiceKey-${sls:stage} # This key will use the provider-level usagePlan functions: hello: handler: handler.hello events: - httpApi: path: /hello method: get private: true # Enforce API key usage # handler.js (example) // exports.hello = async (event) => { // return { // statusCode: 200, // body: JSON.stringify({ message: 'Hello from Serverless API Key!' }), // }; // };

Debug

Known issues

gotchaBy default, the plugin displays the created API key and its value on the console during deployment. This can be a security risk if sensitive keys are logged in CI/CD pipelines or publicly accessible terminals.

fix

To prevent API key values from being displayed on the console, use the `--conceal` option with the `sls deploy` command (e.g., `sls deploy --conceal`).

affects: >=1.0.0

breakingWhen specifying `value` for an API key, ensure it is at least 20 characters long. AWS API Gateway enforces this minimum length, and shorter keys will cause deployment failures.

fix

Ensure all manually specified API key values adhere to the AWS API Gateway minimum length requirement of 20 characters.

affects: >=1.0.0

gotchaIf `usagePlan` is not specified for an individual API key in the `custom.apiKeys` section, the plugin will attempt to use the `usagePlan` configuration from the `provider` section. If neither is specified, an individual usage plan will be created for each key with default settings, which might not be desired.

fix

Explicitly define `usagePlan` for each API key in `custom.apiKeys` if you require specific settings. Alternatively, ensure the `provider.usagePlan` section is configured to provide a sensible default for keys without individual usage plan definitions.

affects: >=1.0.0

gotchaKMS-encrypted API key values require correct configuration of the `encrypted` string and the `kmsKeyRegion`. Incorrect values or missing `kmsKeyRegion` (when different from the deployment region) will lead to decryption failures.

fix

Verify that the `encrypted` value is a valid base64-encoded ciphertext produced by AWS KMS and that `kmsKeyRegion` accurately points to the region where the KMS key resides. Ensure the deployment role has permissions to decrypt with the specified KMS key.

affects: >=3.0.0

Errors

Common errors & fixes

An API key value must be at least 20 characters long.

The `value` specified for an API key in `serverless.yml` is shorter than the AWS API Gateway minimum requirement.

fix

Update the API key `value` to be at least 20 characters long.

Missing region in config

When using KMS encrypted values, if `kmsKeyRegion` is not specified and the environment variable `AWS_REGION` or `AWS_DEFAULT_REGION` is not set, the plugin cannot determine which region to use for decryption.

fix

Provide the `kmsKeyRegion` explicitly in the API key configuration (e.g., `kmsKeyRegion: us-east-1`) or ensure an AWS region is configured in your deployment environment.

Credential profiles the user has configured are not valid for this request.

The AWS credentials used for deployment lack the necessary permissions to create or modify API Gateway API keys and usage plans, or to decrypt KMS values if encrypted keys are used.

fix

Review your IAM role/user policies and ensure they include permissions for `apigateway:CreateApiKey`, `apigateway:UpdateApiKey`, `apigateway:CreateUsagePlan`, `apigateway:UpdateUsagePlan`, `apigateway:GET_API_KEYS`, `apigateway:GET_USAGE_PLANS`, and if using KMS, `kms:Decrypt` for the relevant KMS key.

Upgrade

Version history

4.2.1latest on npm

Audit

Dependencies

serverlessrequiredThis package is a plugin for the Serverless Framework and requires it as a peer dependency.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/rrahul963/serverless-add-api-key ↗

packagehttps://www.npmjs.com/package/serverless-add-api-key ↗