docs/sf/guides/license-keys.md
Starting with Version 4, authentication is required for all users of the Serverless Framework CLI, and License Keys are one method of providing this authentication.
License Keys are merely unique identifiers used to authenticate your access to Serverless Framework V4 and ensure compliance with its licensing model.
They're ideal for organizations that prefer not to use the Serverless Framework Dashboard or its authentication methods. If you want to use only the CLI and avoid remote requests to the Dashboard, License Keys are the solution.
Paid Users and Serverless Framework Dashboard users can optionally use License Keys, or can authenticate through the Dashboard. The CLI provides guidance for Dashboard authentication. Please note that you must have an active subscription to use License Keys.
There are two ways to manage License Keys:
You can manually create, list and delete them within the Serverless Framework Dashboard within the Settings > License Keys view.
Or, you can programatically create, list and delete License Keys using our public API. But first, you need to get your orgId from within the Settings > General view and create an access key from within the Settings > Access Keys view.
Request:
curl -X POST https://core.serverless.com/api/accesskeys/<org-id> \
-H "Authorization: Bearer <access-key>" \
-H "Content-Type: application/json" \
-d '{"label": "example"}'
Response:
{
"data": {
"key": "eyJhbG...",
"label": "example",
"orgId": "<org-id>",
"subscriptionId": "<subscription-id>",
"version": "V2",
"createdAt": 1738686791251,
"updatedAt": 1738686791251
}
}
Request:
curl -X GET https://core.serverless.com/api/accesskeys/<org-id> \
-H "Authorization: Bearer <access-key>"
Response:
{
"data": [
{
"key": "eyJhbG...",
"label": "example",
"orgId": "<org-id>",
"subscriptionId": "<subscription-id>",
"version": "V2",
"createdAt": 1738686791251,
"updatedAt": 1738686791251
}
]
}
Request:
curl -X DELETE https://core.serverless.com/api/accesskeys/<org-id> \
-H "Authorization: Bearer <access-key>" \
-H "Content-Type: application/json" \
-d '{"label": "example", "key": "eyJhbG..." }'
Response:
No response body is returned.
Note: If you are not able to access the Serverless Framework Dashboard, you can have Serverless Inc. create, update and delete them for you by mailing into support.
You can use License Keys in two ways:
SERVERLESS_LICENSE_KEY environment variable in your environment or CI/CD pipeline.export SERVERLESS_LICENSE_KEY=<your-license-key>
This approach is straightforward but requires distributing and maintaining License Keys in multiple locations. It may lead to creating numerous keys to ensure proper separation of concerns, potentially requiring each developer to have their own. This approach is generally hard to scale beyond small teams.
licenseKey field in your serverless.yml configuration file. This supports Variable Resolvers, allowing you to reference keys from secrets management platforms like AWS SSM Params & AWS Secrets Manager or Hashicorp's Vault.service: my-service
# AWS SSM Params & AWS Secrets Manager Example
licenseKey: ${ssm:/path/to/serverless-framework-license-key}
# Vault Example
licenseKey: ${vault:secret/serverless-framework/license-key}
provider:
name: aws
runtime: nodejs20.x
functions:
hello:
handler: handler.hello
This allows you to manage the License Keys securely, without distributing them to teammates or persisting them in lots of locations, and enables easy key rotation if needed.
The most common pattern is to add License Keys to each AWS account the Serverless Framework deploys to, within AWS SSM Params or AWS Secrets Manager. If Serverless Framework has access to deploy to an AWS account, it should have access to read params and secrets from AWS SSM Params and AWS Secrets Manager. No additional changes to the serverless.yml are necessary aside from adding licenseKey.
Serverless Framework Variable Resolvers can reference a separate AWS account from the deployment target, allowing you to store and read the License Key in one AWS account. This requires additional configuration in your serverless.yml files. For more details, refer to our documentation on Variable Resolvers. Using Serverless Framework Compose, you can create a parent Compose file that specifies the AWS account information you want to reference, eliminating the need to replicate this configuration across multiple serverless.yml files.
For more details, refer to
When no licenseKey is specified in the configuration file and the SERVERLESS_LICENSE_KEY environment variable is absent,
the Framework will automatically check for a License Key stored in the /serverless-framework/license-key parameter in
AWS SSM Parameter Store. The Framework reads this parameter using the deployment credentials, applying the same AWS region and profile as the deployment.
To set up the License Key in AWS SSM Parameter Store, you can use the AWS CLI:
aws ssm put-parameter \
--name "/serverless-framework/license-key" \
--description "Serverless Framework License Key" \
--type "SecureString" \
--value "your-license-key" \
--region "your-aws-region" \
--profile "your-aws-profile"
This method is particularly useful for simplifying License Key management in larger teams or projects. It centralizes the License Key storage and eliminates the need for manual configuration in every deployment setup.