Sign inDemoInstall


Package Overview
File Explorer

Advanced tools

Install Socket

Protect your apps from supply chain attacks



Signs and prepares requests using AWS Signature Version 4


Version published
Weekly downloads
decreased by-13.95%

Weekly downloads

Package description

What is aws4?

The aws4 npm package is a library that signs and prepares requests using AWS Signature Version 4. It is used to authenticate and send requests to AWS services that require signing, such as S3, EC2, SES, and others. It can be used both on the server side with Node.js and on the client side in browsers.

What are aws4's main functionalities?

Signing HTTP requests

This feature allows you to sign an HTTP request with AWS Signature Version 4. The code sample demonstrates how to sign a GET request to an AWS service.

{"http": "require('http'), "aws4": "require('aws4'), "opts": { "host": "", "path": "/path/to/resource", "method": "GET" }, "signedOpts": "aws4.sign(opts, { accessKeyId: 'YOURKEY', secretAccessKey: 'YOURSECRET' })", "request": "http.request(signedOpts, function(response) { /* handle response */ })"}

Signing requests for AWS Elasticsearch

This feature is used to sign requests to AWS Elasticsearch service. The code sample shows how to sign a GET request to perform a search operation on an Elasticsearch index.

{"aws4": "require('aws4'), "https": "require('https'), "opts": { "host": "", "path": "/your-index/_search", "method": "GET" }, "signedOpts": "aws4.sign(opts, { accessKeyId: 'YOURKEY', secretAccessKey: 'YOURSECRET' })", "request": "https.request(signedOpts, function(response) { /* handle response */ })"}

Signing requests for AWS S3

This feature is used to sign requests to AWS S3 service. The code sample illustrates how to sign a GET request to retrieve an object from an S3 bucket.

{"aws4": "require('aws4'), "https": "require('https'), "opts": { "host": "", "path": "/bucket/key", "method": "GET" }, "signedOpts": "aws4.sign(opts, { accessKeyId: 'YOURKEY', secretAccessKey: 'YOURSECRET' })", "request": "https.request(signedOpts, function(response) { /* handle response */ })"}

Other packages similar to aws4




Build Status

A small utility to sign vanilla Node.js http(s) request options using Amazon's AWS Signature Version 4.

If you want to sign and send AWS requests in a browser, or an environment like Cloudflare Workers, then check out aws4fetch – otherwise you can also bundle this library for use in older browsers.

The only AWS service that doesn't support v4 as of 2020-05-22 is SimpleDB (it only supports AWS Signature Version 2).

It also provides defaults for a number of core AWS headers and request parameters, making it very easy to query AWS services, or build out a fully-featured AWS library.


var https = require('https')
var aws4  = require('aws4')

// to illustrate usage, we'll create a utility function to request and pipe to stdout
function request(opts) { https.request(opts, function(res) { res.pipe(process.stdout) }).end(opts.body || '') }

// aws4 will sign an options object as you'd pass to http.request, with an AWS service and region
var opts = { host: '', path: '/my-object', service: 's3', region: 'us-west-1' }

// aws4.sign() will sign and modify these options, ready to pass to http.request
aws4.sign(opts, { accessKeyId: '', secretAccessKey: '' })

// or it can get credentials from process.env.AWS_ACCESS_KEY_ID, etc

// for most AWS services, aws4 can figure out the service and region if you pass a host
opts = { host: '', path: '/my-object' }

// usually it will add/modify request headers, but you can also sign the query:
opts = { host: '', path: '/?X-Amz-Expires=12345', signQuery: true }

// and for services with simple hosts, aws4 can infer the host from service and region:
opts = { service: 'sqs', region: 'us-east-1', path: '/?Action=ListQueues' }

// and if you're using us-east-1, it's the default:
opts = { service: 'sqs', path: '/?Action=ListQueues' }

  host: '',
  path: '/?Action=ListQueues',
  headers: {
    Host: '',
    'X-Amz-Date': '20121226T061030Z',
    Authorization: 'AWS4-HMAC-SHA256 Credential=ABCDEF/20121226/us-east-1/sqs/aws4_request, ...'

// we can now use this to query AWS
<?xml version="1.0"?>
<ListQueuesResponse xmlns="">

// aws4 can infer the HTTP method if a body is passed in
// method will be POST and Content-Type: 'application/x-www-form-urlencoded; charset=utf-8'
request(aws4.sign({ service: 'iam', body: 'Action=ListGroups&Version=2010-05-08' }))
<ListGroupsResponse xmlns="">

// you can specify any custom option or header as per usual
  service: 'dynamodb',
  region: 'ap-southeast-2',
  method: 'POST',
  path: '/',
  headers: {
    'Content-Type': 'application/x-amz-json-1.0',
    'X-Amz-Target': 'DynamoDB_20120810.ListTables'
  body: '{}'

// you can also specify extra headers to ignore during signing
  host: '',
  method: 'PUT',
  path: '/my-index',
  body: '{"mappings":{}}',
  headers: {
    'Content-Type': 'application/json',
    'X-Amz-Content-Sha256': 'UNSIGNED-PAYLOAD'
  extraHeadersToIgnore: {
    'content-length': true

// and headers to include that would normally be ignored
  service: 'mycustomservice',
  path: '/whatever',
  headers: {
    'Range': 'bytes=200-1000, 2000-6576, 19000-'
  extraHeadersToInclude: {
    'range': true

// The raw RequestSigner can be used to generate CodeCommit Git passwords
var signer = new aws4.RequestSigner({
  service: 'codecommit',
  host: '',
  method: 'GIT',
  path: '/v1/repos/MyAwesomeRepo',
var password = signer.getDateTime() + 'Z' + signer.signature()

// see example.js for examples with other services


aws4.sign(requestOptions, [credentials])

Calculates and populates any necessary AWS headers and/or request options on requestOptions. Returns requestOptions as a convenience for chaining.

requestOptions is an object holding the same options that the Node.js http.request function takes.

The following properties of requestOptions are used in the signing or populated if they don't already exist:

  • hostname or host (will try to be determined from service and region if not given)
  • method (will use 'GET' if not given or 'POST' if there is a body)
  • path (will use '/' if not given)
  • body (will use '' if not given)
  • service (will try to be calculated from hostname or host if not given)
  • region (will try to be calculated from hostname or host or use 'us-east-1' if not given)
  • signQuery (to sign the query instead of adding an Authorization header, defaults to false)
  • extraHeadersToIgnore (an object with lowercase header keys to ignore when signing, eg { 'content-length': true })
  • extraHeadersToInclude (an object with lowercase header keys to include when signing, overriding any ignores)
  • headers['Host'] (will use hostname or host or be calculated if not given)
  • headers['Content-Type'] (will use 'application/x-www-form-urlencoded; charset=utf-8' if not given and there is a body)
  • headers['Date'] (used to calculate the signature date if given, otherwise new Date is used)

Your AWS credentials (which can be found in your AWS console) can be specified in one of two ways:

  • As the second argument, like this:
aws4.sign(requestOptions, {
  secretAccessKey: "<your-secret-access-key>",
  accessKeyId: "<your-access-key-id>",
  sessionToken: "<your-session-token>"
  • From process.env, such as this:
export AWS_ACCESS_KEY_ID="<your-access-key-id>"
export AWS_SECRET_ACCESS_KEY="<your-secret-access-key>"
export AWS_SESSION_TOKEN="<your-session-token>"

(will also use AWS_ACCESS_KEY and AWS_SECRET_KEY if available)

The sessionToken property and AWS_SESSION_TOKEN environment variable are optional for signing with IAM STS temporary credentials.


With npm do:

npm install aws4

Can also be used in the browser.


Thanks to @jed for his dynamo-client lib where I first committed and subsequently extracted this code.

Also thanks to the official Node.js AWS SDK for giving me a start on implementing the v4 signature.


Last updated on 07 Jan 2023

Did you know?

Socket installs a GitHub app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.


Related posts

SocketSocket SOC 2 Logo


  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc