A simple Python package for refreshing the temporary security credentials in a boto3.session.Session object automatically.

Features

• Drop-in replacement for boto3.session.Session
• Supports automatic credential refresh methods for various AWS services:
  • STS
  • ECS
• Supports custom authentication methods for complicated authentication flows
• Natively supports all parameters supported by boto3.session.Session
• Tested, documented, and published to PyPI
• Future releases will include support for EC2, IoT, SSO, and OIDC

Recognition, Adoption, and Testimonials

Featured in TL;DR Sec.

Featured in CloudSecList.

Recognized during AWS Community Day Midwest on June 5th, 2025.

A testimonial from a Cyber Security Engineer at a FAANG company:

Most of my work is on tooling related to AWS security, so I'm pretty choosy about boto3 credentials-adjacent code. I often opt to just write this sort of thing myself so I at least know that I can reason about it. But I found boto3-refresh-session to be very clean and intuitive [...] We're using the RefreshableSession class as part of a client cache construct [...] We're using AWS Lambda to perform lots of operations across several regions in hundreds of accounts, over and over again, all day every day. And it turns out that there's a surprising amount of overhead to creating boto3 clients (mostly deserializing service definition json), so we can run MUCH more efficiently if we keep a cache of clients, all equipped with automatically refreshing sessions.

Installation

pip install boto3-refresh-session

Usage (STS)

import boto3_refresh_session as brs

# you can pass all of the params normally associated with boto3.session.Session
profile_name = "<your-profile-name>"
region_name = "us-east-1"
...

# as well as all of the params associated with STS.Client.assume_role
assume_role_kwargs = {
  "RoleArn": "<your-role-arn>",
  "RoleSessionName": "<your-role-session-name>",
  "DurationSeconds": "<your-selection>",
  ...
}

# as well as all of the params associated with STS.Client, except for 'service_name'
sts_client_kwargs = {
  "region_name": region_name,
  ...
}

# basic initialization of boto3.session.Session
session = brs.RefreshableSession(
  assume_role_kwargs=assume_role_kwargs, # required
  sts_client_kwargs=sts_client_kwargs,
  region_name=region_name,
  profile_name=profile_name,
  ...
)

Usage (ECS)

session = RefreshableSession(
  method="ecs", 
  region_name=region_name, 
  profile_name=profile_name,
  ...
)

Usage (Custom)

If you have a highly sophisticated, novel, or idiosyncratic authentication flow not included in boto3-refresh-session then you will need to provide your own custom temporary credentials callable object. RefreshableSession accepts custom credentials callable objects, as shown below.

# create (or import) your custom credential method
def your_custom_credential_getter(...):
    ...
    return {
        "access_key": ...,
        "secret_key": ...,
        "token": ...,
        "expiry_time": ...,
    }

# and pass it to RefreshableSession
session = RefreshableSession(
    method="custom",
    custom_credentials_method=your_custom_credential_getter,
    custom_credentials_method_args=...,
    region_name=region_name,
    profile_name=profile_name,
    ...
)