{"id":16210,"library":"serverless-add-api-key","title":"Serverless API Key Management Plugin","description":"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.","status":"active","version":"4.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/rrahul963/serverless-add-api-key","tags":["javascript","api","key","gateway","usage","pattern"],"install":[{"cmd":"npm install serverless-add-api-key","lang":"bash","label":"npm"},{"cmd":"yarn add serverless-add-api-key","lang":"bash","label":"yarn"},{"cmd":"pnpm add serverless-add-api-key","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a plugin for the Serverless Framework and requires it as a peer dependency.","package":"serverless","optional":false}],"imports":[{"note":"Serverless plugins are loaded via the `plugins` array in `serverless.yml`, not directly imported in JavaScript/TypeScript code.","wrong":"require('serverless-add-api-key')","symbol":"plugin entry","correct":"plugins:\n  - serverless-add-api-key"},{"note":"Configuration for the plugin resides under the `custom.apiKeys` section in `serverless.yml`. Ensure correct YAML indentation and structure.","wrong":"apiKeys:\n  - name: MyServiceKey","symbol":"API Key configuration","correct":"custom:\n  apiKeys:\n    - name: MyServiceKey\n      value: ${ssm:/aws/reference/secretsmanager/my-api-secret~partial}\n      usagePlan:\n        name: MyUsagePlan\n        throttle:\n          rateLimit: 10\n          burstLimit: 20"},{"note":"For KMS-encrypted values, the `value` property must be an object with `encrypted` and optionally `kmsKeyRegion` keys. Raw encrypted strings will not be decrypted.","wrong":"value: 'AQICAH...'","symbol":"KMS encrypted value","correct":"custom:\n  apiKeys:\n    - name: SecureKey\n      value:\n        encrypted: A-KMS-Encrypted-Value\n        kmsKeyRegion: us-east-1"}],"quickstart":{"code":"service: my-serverless-api\n\nprovider:\n  name: aws\n  runtime: nodejs18.x\n  stage: dev\n  region: us-east-1\n  usagePlan:\n    name: default-api-usage-plan\n    description: Default plan for my-serverless-api\n    throttle:\n      rateLimit: 10\n      burstLimit: 5\n    quota:\n      limit: 1000\n      period: DAY\n\nplugins:\n  - serverless-add-api-key\n\ncustom:\n  apiKeys:\n    - name: MyServiceGlobalKey-${sls:stage}\n      value: ${env:MY_API_KEY_VALUE, 'default-secure-key-1234567890'}\n      usagePlan:\n        name: CustomUsagePlanForGlobalKey-${sls:stage}\n        description: Usage plan specific to the global key for this stage\n        throttle:\n          rateLimit: 20\n          burstLimit: 10\n        quota:\n          limit: 5000\n          period: MONTH\n    - name: MyEncryptedKey-${sls:stage}\n      value:\n        encrypted: AQICAHinIKhx8yV+y97+qS5naGEBUQrTP8RPE4HDnVvd0AzJ/wGF2tC0dPMHO... # Replace with actual KMS encrypted value\n        kmsKeyRegion: us-east-1 # Specify the region where the KMS key is located\n    - name: AnotherServiceKey-${sls:stage} # This key will use the provider-level usagePlan\n\nfunctions:\n  hello:\n    handler: handler.hello\n    events:\n      - httpApi:\n          path: /hello\n          method: get\n          private: true # Enforce API key usage\n\n# handler.js (example)\n// exports.hello = async (event) => {\n//   return {\n//     statusCode: 200,\n//     body: JSON.stringify({ message: 'Hello from Serverless API Key!' }),\n//   };\n// };","lang":"yaml","description":"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."},"warnings":[{"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`).","message":"By 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure all manually specified API key values adhere to the AWS API Gateway minimum length requirement of 20 characters.","message":"When 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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"If `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"KMS-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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Update the API key `value` to be at least 20 characters long.","cause":"The `value` specified for an API key in `serverless.yml` is shorter than the AWS API Gateway minimum requirement.","error":"An API key value must be at least 20 characters long."},{"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.","cause":"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.","error":"Missing region in config"},{"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.","cause":"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.","error":"Credential profiles the user has configured are not valid for this request."}],"ecosystem":"npm"}