aws4-axios

library3.4.0jsnpmunverified

Axios request interceptor for signing HTTP requests with AWS Signature Version 4 (AWSv4). Version 3.4.0 requires Node >=16 and axios >=1.6.0. Supports explicit credentials, custom credential providers, and content SHA headers for services like OpenSearch Serverless. v3 includes a breaking API change: options are now nested under an `options` property. Ships TypeScript definitions. Suitable for accessing AWS services protected by IAM auth (e.g., API Gateway).

devops

npm install aws4-axios

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AWS4-AXIOS

aws4-axios

devopsjavascriptv3.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

aws4Interceptor

✓ import { aws4Interceptor } from 'aws4-axios'

✗ const aws4Interceptor = require('aws4-axios')

ESM-only package; CommonJS require() does not work directly.

Aws4InterceptorConfig

✓ import type { Aws4InterceptorConfig } from 'aws4-axios'

✗ import { Aws4InterceptorConfig } from 'aws4-axios'

Config type is a type-only export, import using `import type` in TypeScript.

CredentialsProvider

✓ import type { CredentialsProvider } from 'aws4-axios'

✗ import { CredentialsProvider } from 'aws4-axios'

CredentialsProvider is an interface, use `import type`.

Creates an Axios interceptor that signs requests with AWS Signature V4 using explicit credentials from environment variables. Use with an Axios instance.

import axios from 'axios'; import { aws4Interceptor } from 'aws4-axios'; const interceptor = aws4Interceptor({ options: { region: 'us-east-1', service: 'execute-api', addContentSha: false, }, credentials: { accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '', secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? '', }, }); const client = axios.create(); client.interceptors.request.use(interceptor); client.get('https://example.com/api/resource') .then(response => console.log(response.data)) .catch(err => console.error(err));

Debug

Known issues

breakingv3 changed the interface: options now must be nested under an `options` property. Passing region/service at the top level will be ignored.

fix

Wrap your options in { options: { region: '...', service: '...' } }.

affects: >=3.0.0 <4.0.0

gotchaOnly axios versions 1.4.0 through 1.6.7 are officially supported. Using axios 1.7.0 or later may cause silent failures or runtime errors.

fix

Pin axios to '>=1.4.0 <=1.6.7' in your package.json.

affects: *

deprecatedThe `assumeRoleArn` option is deprecated in v3. Use a custom CredentialsProvider instead.

fix

Implement a CredentialsProvider that assumes the role via STS and returns temporary credentials.

affects: >=3.0.0

gotchaThe interceptor mutates the Axios request config. If you reuse config objects across requests, they may retain signed headers.

fix

Do not reuse Axios config objects; create fresh configs per request or clone before signing.

affects: *

Errors

Common errors & fixes

TypeError: aws4Interceptor is not a function

CommonJS require() used with ESM-only package.

fix

Use import syntax or enable ESM in your project.

AWS4Axios[ERR]: region is required

Options not nested properly in v3; region passed at top level instead of inside options.

fix

Use { options: { region: '...', service: '...' } }.

Cannot read properties of undefined (reading 'getCredentials')

Credentials provider object does not implement the getCredentials method.

fix

Ensure the provider has an async getCredentials method returning an object with accessKeyId and secretAccessKey.

Upgrade

Version history

3.4.0latest on npm

Audit

Dependencies

axiosrequiredpeer dependency; the interceptor is designed to work with Axios v1.4.0–1.6.7 (inclusive).

Agent activity

12 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/jamesmbourne/aws4-axios ↗

packageaws4-axios ↗

homepagehttps://github.com/jamesmbourne/aws4-axios ↗