AWS Requests Auth

raw JSON →
0.4.3 verified Tue May 12 auth: no python install: verified

aws-requests-auth (version 0.4.3) is a Python library that implements the AWS Signature Version 4 signing process for the popular `requests` module. It enables authentication to AWS services that support Signature Version 4, originally designed for AWS Elasticsearch instances but extensible to other services. The library has been stable since its last release in May 2020.

pip install aws-requests-auth

Common errors

error SignatureDoesNotMatch ↓
cause The request signature doesn't conform to AWS standards.
fix
Ensure that your AWS Secret Access Key is correctly configured and that the 'sts_region' matches the AWS region where your IAM roles are deployed.
error AccessDeniedException ↓
cause You don't have sufficient access to perform this action.
fix
Verify that your IAM policy includes the required permissions.
error ExpiredTokenException ↓
cause The security token included in the request is expired.
fix
Request a new security token and try again.
error IncompleteSignature ↓
cause The request signature doesn't conform to AWS standards.
fix
Verify that you're using valid AWS credentials and that your request is properly formatted.
error UnrecognizedClientException ↓
cause The AWS access key ID provided does not exist in our records.
fix
Verify that you're using valid credentials and that they haven't expired.

Warnings

gotcha Incorrect or expired AWS credentials (access key, secret key, session token) or an invalid combination of host, region, and service are common causes of authentication failures. AWS will respond with errors like `InvalidClientTokenId` or `SignatureDoesNotMatch` if the request cannot be authenticated. ↓
fix Double-check that `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`, `aws_host`, and `aws_service` are correctly configured. If using STS temporary credentials, ensure `AWS_SESSION_TOKEN` is provided via the `aws_token` argument.
gotcha When deploying applications using `aws-requests-auth` to serverless environments (e.g., AWS Lambda), ensure the library, along with its dependencies (like `requests`), is correctly bundled in your deployment package. Failure to do so can result in `Runtime.ImportModuleError` (e.g., `No module named 'aws_requests_auth'`). ↓
fix Include `aws-requests-auth` and its dependencies in your `requirements.txt` and ensure your build process (e.g., `sam build` for AWS SAM) correctly packages them.
gotcha If using the `BotoAWSRequestsAuth` class for automatic credential retrieval, `botocore` is an optional dependency that must be installed. Without `botocore`, `BotoAWSRequestsAuth` cannot function and may lead to runtime errors or incorrect credential handling. ↓
fix If you intend to use `BotoAWSRequestsAuth`, ensure you install `botocore` explicitly: `pip install botocore`.
gotcha When making requests to AWS services, if the configured endpoint hostname (e.g., `aws_host`) cannot be resolved via DNS, the request will fail with a `NameResolutionError`. This indicates that the system cannot find an IP address for the specified hostname. ↓
fix Verify that the `aws_host` (or equivalent endpoint configuration) is spelled correctly and is a valid, resolvable hostname. Check your network configuration and DNS settings to ensure that external hostnames can be resolved from the environment where the application is running.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk
3.10 alpine (musl) wheel - 0.55s 21.2M
3.10 alpine (musl) - - 0.56s 21.2M
3.10 slim (glibc) wheel 2.3s 0.39s 22M
3.10 slim (glibc) - - 0.40s 22M
3.11 alpine (musl) wheel - 0.71s 23.2M
3.11 alpine (musl) - - 0.76s 23.2M
3.11 slim (glibc) wheel 2.2s 0.64s 24M
3.11 slim (glibc) - - 0.58s 24M
3.12 alpine (musl) wheel - 0.65s 15.0M
3.12 alpine (musl) - - 0.67s 15.0M
3.12 slim (glibc) wheel 2.0s 0.66s 16M
3.12 slim (glibc) - - 0.66s 16M
3.13 alpine (musl) wheel - 0.71s 14.8M
3.13 alpine (musl) - - 0.66s 14.7M
3.13 slim (glibc) wheel 1.9s 0.63s 15M
3.13 slim (glibc) - - 0.65s 15M
3.9 alpine (musl) wheel - 0.51s 20.4M
3.9 alpine (musl) - - 0.50s 20.5M
3.9 slim (glibc) wheel 2.5s 0.44s 21M
3.9 slim (glibc) - - 0.42s 21M

Imports

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to use `AWSRequestsAuth` to sign a request to an AWS service endpoint. Replace `your-aws-endpoint.amazonaws.com` and the service-specific path (`/_cat/health`) with your actual AWS service endpoint and path. Credentials are retrieved from environment variables for security and flexibility, with fallbacks for demonstration.

import requests
import os
from aws_requests_auth.aws_auth import AWSRequestsAuth

aws_access_key = os.environ.get('AWS_ACCESS_KEY_ID', 'YOUR_ACCESS_KEY')
aws_secret_key = os.environ.get('AWS_SECRET_ACCESS_KEY', 'YOUR_SECRET_KEY')
aws_region = os.environ.get('AWS_DEFAULT_REGION', 'us-east-1')
aws_service = 'es' # Example service, e.g., 'es' for Elasticsearch, 's3', 'execute-api'
aws_host = 'your-aws-endpoint.amazonaws.com'

# For STS temporary credentials, include aws_token
aws_token = os.environ.get('AWS_SESSION_TOKEN')

auth = AWSRequestsAuth(
    aws_access_key=aws_access_key,
    aws_secret_access_key=aws_secret_key,
    aws_host=aws_host,
    aws_region=aws_region,
    aws_service=aws_service,
    aws_token=aws_token # Pass if using STS temporary credentials
)

try:
    # Replace with your actual endpoint
    response = requests.get(f'https://{aws_host}/_cat/health', auth=auth, timeout=10)
    response.raise_for_status() # Raise an exception for HTTP errors
    print("Successfully authenticated and received response:")
    print(response.text)
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")
    if hasattr(e, 'response') and e.response is not None:
        print(f"Response Status Code: {e.response.status_code}")
        print(f"Response Body: {e.response.text}")
    print("Please ensure your AWS credentials, host, region, and service are correct.")
last verified Tue May 12
next check Sat Jun 27