Serverless API Key Management Plugin

Common errors

• An API key value must 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.
  fix Update the API key `value` to be at least 20 characters long.

• Missing region in config

  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.
  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.

  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.
  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.

Warnings

• gotcha 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.
  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`).
• breaking 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.
  Fix: Ensure all manually specified API key values adhere to the AWS API Gateway minimum length requirement of 20 characters.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install serverless-add-api-key npm
• yarn add serverless-add-api-key yarn
• pnpm add serverless-add-api-key pnpm

Imports

• plugin entry
  wrong:

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

  correct:

  plugins:
    - 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
  wrong:

  apiKeys:
    - name: MyServiceKey

  correct:

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

  Configuration for the plugin resides under the `custom.apiKeys` section in `serverless.yml`. Ensure correct YAML indentation and structure.
• KMS encrypted value
  wrong:

  value: 'AQICAH...'

  correct:

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

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

Quickstart

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!' }),
//   };
// };