serverless-add-api-key
A serverless plugin to create api key and usage pattern (if they don't already exist) and associate them to the Rest Api. Serverless provides this functionality natively but it doesn't allow you to associate multiple services with same apiKey and usage plan. This plugin associates your Serverless service with same api key if the key already exists. Also works with multiple keys.
The plugin supports serverless stages, so you can create key(s) with different name in different stage.
P.S. The plugin by default displays the created key and value on the console. If you wish to avoid that then specify --conceal
option with sls deploy
command
Install
npm install --save-dev serverless-add-api-key
Add the plugin to your serverless.yml
file:
plugins:
- serverless-add-api-key
Configuration
Specifying key(s) and let AWS auto set the value - this is the minimum required configuration to use this plugin
custom:
apiKeys:
- name: name1
- name: name2
Specifying key values
custom:
apiKeys:
- name: SomeKey
value: your-api-key-that-is-at-least-20-characters-long
- name: KeyFromSlsVariables
value: ${opt:MyKey}
Specifying encrypted key values
In the case that you do not want to expose your raw API key string in your repository, you could check in the encrypted API key strings using KMS key in a region. To do this, first Use a KMS key in the region from command line to encrypt the key:
aws kms encrypt --key-id f7c59c6b-83de-4e80-8011-0fbd6846c695 --plaintext BzQ86PiX9t9UaAQsNWuFHN9oOkiyOwd9yXBu8RF1 | base64 --decode
Then configure the value
as { encrypted: "AQICAHinIKhx8yV+y97+qS5naGEBUQrTP8RPE4HDnVvd0AzJ/wGF2tC0dPMHO..." }
custom:
apiKeys:
- name: KMSEncryptedKey
value:
encrypted: A-KMS-Encrypted-Value
kmsKeyRegion: us-west-1
When an object with encrypted
and kmsKeyRegion
key detected in value
, the encrypted value will be decrypted using a proper KMS key from the region specified in kmsKeyRegion
. In the case of missing kmsKeyRegion
, the region from command line will be used.
Specifying usage plan
custom:
apiKeys:
- name: KeyWithFullUsagePlanDetail
usagePlan:
name: "name-of-first-usage-plan" (required if usagePlan is specified. rest of the fields are optional)
description: "Description of first plan"
quota:
limit: 1000
period: DAY
throttle:
burstLimit: 100
rateLimit: 20
- name: KeyWithOnlyUsagePlanName
usagePlan:
name: "name-of-first-usage-plan"
- name: AKeyWithNoUsagePlan
- name: KeyWithNoUsagePlanButValue
value: SomeKeyValue
provider: // this is optional - plugin will use this if usage plan options are not provided in custom section as above
usagePlan:
name: "default-usage-plan-name"
description: "Used for serverless as the default for the process or for custom apiKeys above if no usagePlan is provided"
quota:
limit: 5000
period: DAY
throttle:
burstLimit: 100
rateLimit: 50
If the usage plan needs to be created, first it will look for a usagePlan property that is an object with a name property. If it does not find that it will use the usagePlan attributes defined in the provider
section, if defined.
NOTE:
- If not specified in the configuration, an individual usagePlan will be created for each key listed.
For example,
AKeyWithNoUsagePlan
will have an individual usage plan namedAKeyWithNoUsagePlan-usage-plan
with no restrictions. - When UsagePlan configuration is provided under
provider
section, serverless automatically creates a usage plan named<service-name>-plan
, but this plugin is not using that usage plan.
Stage-specific configuration
To specify different API keys for each stage, nest the configuration in a property with the name of the relevant stage. Note - When specifying the keys for each stage, you can use any of the above configuration like providing value/encrypted value and usage plan.
custom:
apiKeys:
dev:
- name: name1
- name: name2
prod:
- name: name1
other-stage-name:
- name: name5
Remove Api Key(s) and Usage plan(s)
Run severless remove command to remove the created api key and usage plan. If the Usage plan is associated with more than one api then the plan and key will be deleted only when the last service is removed.
If you dont want to delete a key as part of sls remove
command then you can set deleteAtRemoval
as false
(default is true
if not set)
custom:
apiKeys:
- name: name1
deleteAtRemoval: false
- name: name2
based on above configuration, key name1
will not be deleted when running sls remove
but key name2
will be removed.
For more info on how to get started with Serverless Framework click here.
Revisions:
- 3.3.0 - Added UsagePlan settings
- 3.3.1 - Added unit tests, examples and travis-ci
- 4.0.0
- Added Remove hook
- Added option to read the usage plan name from the provider section.
- 4.0.1 - Updated unit tests and added pre-commit and pre-push hooks using husky
- 4.0.2 - Fixed usagePlan config selection criterion
- 4.1.0 - Added an option to not delete apiKey with sls remove
- 4.1.1 - Fixed the issue with deleteAtRemoval not working consistently
- 4.2.0 - Added support for httpOptions when creating AWS service objects