AWS Credentials
The Serverless Framework creates and manages resources in your AWS account, so every command that talks to AWS needs AWS credentials. This page shows the ways to provide them (browser sign-in, AWS IAM Identity Center (SSO), profiles, environment variables, credential resolvers in serverless.yml, and Serverless Dashboard providers) and which one a deploy uses when several are available.
On your own machine, sign in through the AWS Console in a browser and deploy:
serverless login aws
serverless deploy
serverless login aws stores short-lived credentials in the default AWS profile. In CI/CD, where nothing can open a browser, use environment variables or a role instead (see Running in your own CI/CD).
Which credentials a deploy uses
A deploy takes its AWS credentials from the first of these that applies:
- The
awsresolver named byprovider.resolver, or, whenprovider.profileis not set, the service's onlytype: awsresolver, with a stage's block overriding a same-named one instages.default(see Using resolvers to specify deployment credentials). --aws-profileon the command line.provider.profileinserverless.yml.- The standard AWS credential provider chain:
AWS_PROFILE,AWS_ACCESS_KEY_IDandAWS_SECRET_ACCESS_KEY, then the shared config files.
If the service sets org and app and a Serverless Dashboard Provider applies to it, the Provider's credentials are used ahead of all of these, unless the resolver from step 1 sets dashboard: false.
When a resolver supplies the credentials, --aws-profile is ignored. Run serverless agent setup --stage <stage> to see which source a deploy to that stage would use, and whether AWS accepts it.
Sign in with the AWS Console
serverless login aws signs you in through the AWS Console in a browser and creates short-lived credentials, without long-term access keys:
-
Run the command in an interactive terminal:
serverless login aws -
Complete the sign-in in the browser that opens. The CLI saves the session token under
~/.aws/login/cache/and points thedefaultprofile in~/.aws/config(or the file inAWS_CONFIG_FILE) at it. To use another profile, add--aws-profile <name>(seelogin aws). -
Deploy:
serverless deploy
The command needs an interactive terminal: in CI or other non-interactive environments, it stops with an error.
AWS keeps the session valid for up to 12 hours. After it ends, commands stop with an error that starts with AWS credentials missing or invalid and ends with:
Original error from AWS: Your session has expired. Please reauthenticate.
Run serverless login aws again to start a new session.
Use the AWS credential provider chain
Without a resolver or profile setting, the Framework reads credentials through the AWS credential provider chain, the same sources the AWS CLI and SDKs use:
- Environment variables:
AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEYand, for temporary credentials,AWS_SESSION_TOKEN. - AWS IAM Identity Center (SSO): configure a profile with
aws configure sso, then sign in (and sign in again when the session expires) withserverless login aws ssooraws sso login. - Profiles: named profiles in
~/.aws/credentialsand~/.aws/config. Choose one with--aws-profile,provider.profileinserverless.yml, or theAWS_PROFILEenvironment variable. - Instance roles: on an EC2 instance or in a container with an IAM role, the role's credentials.
If an MFA device protects a profile's role, the CLI prompts for the code.
The AWS SDK's own SSO and STS clients use the same proxy settings as the Framework's AWS requests: set HTTPS_PROXY (or HTTP_PROXY as a fallback; lowercase names work too) when these requests must go through a proxy, and NO_PROXY=.amazonaws.com to bypass it for AWS endpoints.
Save access keys in a local profile
When serverless runs onboarding and finds no valid AWS credentials, it offers to set them up. Choose Save AWS Credentials in a Local Profile to store long-term access keys:
- Run
serverlessin your terminal. - Choose Save AWS Credentials in a Local Profile.
- Follow the printed instructions: in the AWS IAM console, create an IAM user with the policy the instructions name (they suggest
AdministratorAccess; attach a narrower policy if your organization requires one), then create an access key for it. - Enter the Access Key ID and Secret Access Key when prompted.
The CLI writes the keys to the default profile in ~/.aws/credentials, replacing the keys already in that profile. Later commands read them through the credential provider chain.
To configure credentials another way (SSO, environment variables), choose Skip & Set Later (AWS SSO, ENV Vars) instead.
Using resolvers to specify deployment credentials
A resolver of type: aws in serverless.yml describes an AWS account: a profile or access keys, and a Region. One resolver can supply the deployment credentials, and every resolver can also read variables from its account.
Defining resolvers
Declare resolvers under stages.<stage>.resolvers; a resolver under stages.default applies to every stage that doesn't declare one with the same name:
stages:
default:
resolvers:
aws-account-1:
type: aws
profile: account1-profile-name
region: us-west-2
With this as the service's only type: aws resolver, deploys use the account1-profile-name profile. For all options, see the AWS resolver documentation.
Using multiple resolvers
With more than one type: aws resolver, for example one account for shared variables and another for the deployment, set provider.resolver to the resolver that supplies the deployment credentials:
service: my-service
stages:
default:
resolvers:
shared-account:
type: aws
region: us-east-1
accessKeyId: ${env:SHARED_ACCOUNT_AWS_ACCESS_KEY_ID}
secretAccessKey: ${env:SHARED_ACCOUNT_AWS_SECRET_ACCESS_KEY}
project-specific-account:
type: aws
region: us-west-2
profile: project-specific-profile
provider:
name: aws
resolver: project-specific-account
functions:
hello:
handler: handler.hello
environment:
ACCOUNT_ID: ${project-specific-account:accountId}
SHARED_VAR: ${shared-account:ssm:/path/to/param}
project-specific-account supplies the deployment credentials, and both resolvers supply variables from their accounts.
Resolver and profile rules
provider.profileandprovider.resolvercan't be set together: the command stops withThe provider.profile and provider.resolver cannot be set at the same time.- With neither set and a single
type: awsresolver (a name in bothstages.defaultand the current stage counts once), that resolver supplies the deployment credentials. - With
provider.profileset,provider.profilewins over a singletype: awsresolver. - With several
type: awsresolvers and noprovider.profile,provider.resolveris required; otherwise the command stops withMultiple resolvers with type "aws" found. Please specify the credential provider to use for deployment in the provider.resolver key.
Overriding a resolver's profile
To let one person or one run use another profile without editing the resolver, give its profile a variable with the team's default. A parameter keeps the default next to the stage and takes a one-off override on the command line:
stages:
staging:
params:
awsProfile: staging-account
resolvers:
aws-account:
type: aws
profile: ${param:awsProfile}
serverless deploy --stage staging --param "awsProfile=my-staging"
For an override that stays on one machine, use an environment variable instead: profile: ${env:STAGING_AWS_PROFILE, 'staging-account'}.
Using Serverless Dashboard Providers with resolvers
When the service sets org and app and a Dashboard Provider applies to it, every type: aws resolver uses the Provider's credentials. To use the resolver's own profile or keys instead, set dashboard: false on it:
service: my-service
org: my-org
app: my-app
stages:
default:
resolvers:
local-profile-account:
type: aws
dashboard: false
region: us-west-2
profile: project-specific-profile
dashboard-provider-account:
type: aws
provider:
name: aws
resolver: local-profile-account
Here local-profile-account supplies the deployment credentials from the local profile project-specific-profile, and dashboard-provider-account resolves variables with the Provider's credentials.
Use a Serverless Dashboard Provider
A Serverless Dashboard Provider stores the connection to an AWS account (an IAM role the Dashboard assumes) in your Dashboard org, so no AWS credentials live on your machine or in CI. A Provider applies only to services that set org and app in serverless.yml. To add one to an existing service, see the Provider documentation.
To create a new service connected through a Provider:
- In an empty directory, run
serverless. - Choose a template, for example AWS / Node.js / HTTP API.
- Enter a service name. The CLI creates a directory with that name and adds the template's files.
- Choose Login/Register and sign in to the Serverless Dashboard in the browser, or create an account (you can create an org with the right name later). Return to the terminal.
- Create an App or select one. Don't skip this step: the Provider is used only with
organdappset. - When asked about AWS credentials, choose Create AWS IAM Role (Easy & Recommended).
- Open the CloudFormation link the terminal prints, signed in to the AWS account you want to use. Keep the defaults, tick the box acknowledging that AWS CloudFormation might create IAM resources, and choose Create stack.
- When the stack is created, the terminal detects the new Provider. Follow the next steps it prints, then run
serverless deployin the new directory.
If your machine already has AWS credentials, or your org already has a default Provider, onboarding skips the AWS credentials question. A Provider linked to the service (or the org's default Provider) is still used ahead of your local credentials when serverless.yml sets org and app and you are logged in with serverless login.
Set up AWS accounts for production
For production applications, use several AWS accounts managed with AWS Organizations: a management account that holds no workloads, separate accounts for production and development, and optionally one account per developer. Each Serverless Framework stage then deploys to its own account.
Management account
The management account only manages the other accounts and their users:
- Sign in to the new account, usually created with an alias email address for your team, and open the Organizations service.

- Choose Create an organization. The account you are signed in to is listed as the management account.

- Open IAM Identity Center and choose Enable.
IAM Identity Center gives your users an AWS access portal URL, which you can customize later.

- Under Users, choose Add user and enter your own email address and details.

- Skip adding the user to groups: choose Next, review, and choose Add user.
- Under AWS accounts, select the management account.

- Choose Assign users or groups.

- On the Users tab, select the new user and choose Next.

- Choose Create permission set, which opens a new tab.

- Choose a predefined permission set.
AdministratorAccessgets you started; replace it with a narrower set when your team's needs are clear.
- Choose any session duration (it limits how long a signed-in user's session lasts and doesn't affect Dashboard Providers), choose Next, then Create.

- Close the tab and return to the assignment. Refresh if the new permission set isn't listed, select it, choose Next, then Submit.

The new user receives an email to activate the account. Add further users the same way.
Stage accounts for production and development
Separate accounts keep experimental changes out of the account that serves your customers:
- In Organizations, choose Add an AWS account.
- Give the account a name that marks it as the development account.
- Use an alias email address for the account's root user.
- Choose Create AWS account.
- In IAM Identity Center, under AWS accounts, select the new account and choose Assign users or groups. Select the users or groups that work in this account, choose Next, select a permission set, choose Next, then Submit. A new account grants access only to the users and groups assigned to it.
- Repeat for the production account.
Developer accounts
Shared development accounts can still lead developers to overwrite each other's stacks. Create one account per developer the same way, which isolates their deployments and is managed through Organizations as people join and leave the team.
Combine accounts with Dashboard Providers
With the accounts in place, create a Dashboard Provider for each account and link it to the stages that deploy there.
Related pages
- Dashboard Providers: AWS access through the Serverless Dashboard.
- AWS resolver: every option of
type: awsresolvers. serverless login awsandserverless login aws sso: the sign-in commands.- Running in your own CI/CD: credentials in a pipeline.