<div align="center">
<img src="https://raw.githubusercontent.com/michaelthomasletts/boto3-refresh-session/refs/heads/main/doc/brs.png" />
</div>
</br>
<div align="center"><em>
A simple Python package for refreshing the temporary security credentials in a <code>boto3.session.Session</code> object automatically.
</em></div>
</br>
<div align="center">
<a href="https://pypi.org/project/boto3-refresh-session/">
<img src="https://img.shields.io/pypi/v/boto3-refresh-session?color=%23FF0000FF&logo=python&label=Latest%20Version" alt="PyPI - Version"/>
</a>
<a href="https://pypi.org/project/boto3-refresh-session/">
<img src="https://img.shields.io/pypi/pyversions/boto3-refresh-session?style=pypi&color=%23FF0000FF&logo=python&label=Compatible%20Python%20Versions" alt="Python Version"/>
</a>
<a href="https://github.com/michaelthomasletts/boto3-refresh-session/actions/workflows/push.yml">
<img src="https://img.shields.io/github/actions/workflow/status/michaelthomasletts/boto3-refresh-session/push.yml?logo=github&color=%23FF0000FF&label=Build" alt="Workflow"/>
</a>
<a href="https://github.com/michaelthomasletts/boto3-refresh-session/commits/main">
<img src="https://img.shields.io/github/last-commit/michaelthomasletts/boto3-refresh-session?logo=github&color=%23FF0000FF&label=Last%20Commit" alt="GitHub last commit"/>
</a>
<a href="https://github.com/michaelthomasletts/boto3-refresh-session/stargazers">
<img src="https://img.shields.io/github/stars/michaelthomasletts/boto3-refresh-session?style=flat&logo=github&labelColor=555&color=FF0000&label=Stars" alt="Stars"/>
</a>
<a href="https://pypistats.org/packages/boto3-refresh-session">
<img src="https://img.shields.io/badge/downloads-72.1K-red?logo=python&color=%23FF0000&label=Downloads%20%28with%20mirrors%29" alt="Downloads with mirrors"/>
</a>
<a href="https://pypistats.org/packages/boto3-refresh-session">
<img src="https://img.shields.io/badge/downloads-18.1K-red?logo=python&color=%23FF0000&label=Downloads%20%28without%20mirrors%29" alt="Downloads without mirrors"/>
</a>
<a href="https://michaelthomasletts.github.io/boto3-refresh-session/index.html">
<img src="https://img.shields.io/badge/Official%20Documentation-📘-FF0000?style=flat&labelColor=555&logo=readthedocs" alt="Documentation Badge"/>
</a>
<a href="https://github.com/michaelthomasletts/boto3-refresh-session">
<img src="https://img.shields.io/badge/Source%20Code-💻-FF0000?style=flat&labelColor=555&logo=github" alt="Source Code Badge"/>
</a>
<a href="https://michaelthomasletts.github.io/boto3-refresh-session/qanda.html">
<img src="https://img.shields.io/badge/Q%26A-❔-FF0000?style=flat&labelColor=555&logo=vercel&label=Q%26A" alt="Q&A Badge"/>
</a>
<a href="https://medium.com/@lettsmt/you-shouldnt-have-to-think-about-refreshing-aws-credentials-214f7cbbd83b">
<img src="https://img.shields.io/badge/Medium%20Article-📘-FF0000?style=flat&labelColor=555&logo=readthedocs" alt="Medium Article"/>
</a>
<a href="https://github.com/sponsors/michaelthomasletts">
<img src="https://img.shields.io/badge/Sponsor%20this%20Project-💙-FF0000?style=flat&labelColor=555&logo=githubsponsors" alt="Sponsorship"/>
</a>
</div>
## 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](https://github.com/michaelthomasletts/boto3-refresh-session/tree/main/tests), [documented](https://michaelthomasletts.github.io/boto3-refresh-session/index.html), and [published to PyPI](https://pypi.org/project/boto3-refresh-session/)
- Future releases will include support for EC2, IoT, SSO, and OIDC
## Recognition, Adoption, and Testimonials
[Featured in TL;DR Sec.](https://tldrsec.com/p/tldr-sec-282)
[Featured in CloudSecList.](https://cloudseclist.com/issues/issue-290)
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
```bash
pip install boto3-refresh-session
```
## Usage (STS)
Most users use AWS STS to assume an IAM role and return a set of temporary security credentials. boto3-refresh-session can be used to ensure those temporary credentials refresh automatically.
```python
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)
You can use boto3-refresh-session in an ECS container to automatically refresh temporary security credentials.
```python
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.
```python
# 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,
...
)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/michaelthomasletts/boto3-refresh-session",
"name": "boto3-refresh-session",
"maintainer": "Michael Letts",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "lettsmt@gmail.com",
"keywords": "boto3, botocore, aws, sts, ecs, credentials, token, refresh",
"author": "Mike Letts",
"author_email": "lettsmt@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/3a/64/b4b3c76e2888e5c116e9f0a2714b4375b45d3b1236807f71663a03e763a9/boto3_refresh_session-1.3.18.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <img src=\"https://raw.githubusercontent.com/michaelthomasletts/boto3-refresh-session/refs/heads/main/doc/brs.png\" />\n</div>\n\n</br>\n\n<div align=\"center\"><em>\n A simple Python package for refreshing the temporary security credentials in a <code>boto3.session.Session</code> object automatically.\n</em></div>\n\n</br>\n\n<div align=\"center\">\n\n <a href=\"https://pypi.org/project/boto3-refresh-session/\">\n <img src=\"https://img.shields.io/pypi/v/boto3-refresh-session?color=%23FF0000FF&logo=python&label=Latest%20Version\" alt=\"PyPI - Version\"/>\n </a>\n\n <a href=\"https://pypi.org/project/boto3-refresh-session/\">\n <img src=\"https://img.shields.io/pypi/pyversions/boto3-refresh-session?style=pypi&color=%23FF0000FF&logo=python&label=Compatible%20Python%20Versions\" alt=\"Python Version\"/>\n </a>\n\n <a href=\"https://github.com/michaelthomasletts/boto3-refresh-session/actions/workflows/push.yml\">\n <img src=\"https://img.shields.io/github/actions/workflow/status/michaelthomasletts/boto3-refresh-session/push.yml?logo=github&color=%23FF0000FF&label=Build\" alt=\"Workflow\"/>\n </a>\n\n <a href=\"https://github.com/michaelthomasletts/boto3-refresh-session/commits/main\">\n <img src=\"https://img.shields.io/github/last-commit/michaelthomasletts/boto3-refresh-session?logo=github&color=%23FF0000FF&label=Last%20Commit\" alt=\"GitHub last commit\"/>\n </a>\n\n <a href=\"https://github.com/michaelthomasletts/boto3-refresh-session/stargazers\">\n <img src=\"https://img.shields.io/github/stars/michaelthomasletts/boto3-refresh-session?style=flat&logo=github&labelColor=555&color=FF0000&label=Stars\" alt=\"Stars\"/>\n </a>\n\n <a href=\"https://pypistats.org/packages/boto3-refresh-session\">\n <img src=\"https://img.shields.io/badge/downloads-72.1K-red?logo=python&color=%23FF0000&label=Downloads%20%28with%20mirrors%29\" alt=\"Downloads with mirrors\"/>\n </a>\n\n <a href=\"https://pypistats.org/packages/boto3-refresh-session\">\n <img src=\"https://img.shields.io/badge/downloads-18.1K-red?logo=python&color=%23FF0000&label=Downloads%20%28without%20mirrors%29\" alt=\"Downloads without mirrors\"/>\n </a> \n\n <a href=\"https://michaelthomasletts.github.io/boto3-refresh-session/index.html\">\n <img src=\"https://img.shields.io/badge/Official%20Documentation-\ud83d\udcd8-FF0000?style=flat&labelColor=555&logo=readthedocs\" alt=\"Documentation Badge\"/>\n </a>\n\n <a href=\"https://github.com/michaelthomasletts/boto3-refresh-session\">\n <img src=\"https://img.shields.io/badge/Source%20Code-\ud83d\udcbb-FF0000?style=flat&labelColor=555&logo=github\" alt=\"Source Code Badge\"/>\n </a>\n\n <a href=\"https://michaelthomasletts.github.io/boto3-refresh-session/qanda.html\">\n <img src=\"https://img.shields.io/badge/Q%26A-\u2754-FF0000?style=flat&labelColor=555&logo=vercel&label=Q%26A\" alt=\"Q&A Badge\"/>\n </a>\n\n <a href=\"https://medium.com/@lettsmt/you-shouldnt-have-to-think-about-refreshing-aws-credentials-214f7cbbd83b\">\n <img src=\"https://img.shields.io/badge/Medium%20Article-\ud83d\udcd8-FF0000?style=flat&labelColor=555&logo=readthedocs\" alt=\"Medium Article\"/>\n </a>\n\n<a href=\"https://github.com/sponsors/michaelthomasletts\">\n <img src=\"https://img.shields.io/badge/Sponsor%20this%20Project-\ud83d\udc99-FF0000?style=flat&labelColor=555&logo=githubsponsors\" alt=\"Sponsorship\"/>\n</a>\n\n\n</div>\n\n## Features\n\n- Drop-in replacement for `boto3.session.Session`\n- Supports automatic credential refresh methods for various AWS services:\n - STS\n - ECS\n- Supports custom authentication methods for complicated authentication flows\n- Natively supports all parameters supported by `boto3.session.Session`\n- [Tested](https://github.com/michaelthomasletts/boto3-refresh-session/tree/main/tests), [documented](https://michaelthomasletts.github.io/boto3-refresh-session/index.html), and [published to PyPI](https://pypi.org/project/boto3-refresh-session/)\n- Future releases will include support for EC2, IoT, SSO, and OIDC\n\n## Recognition, Adoption, and Testimonials\n\n[Featured in TL;DR Sec.](https://tldrsec.com/p/tldr-sec-282)\n\n[Featured in CloudSecList.](https://cloudseclist.com/issues/issue-290)\n\nRecognized during AWS Community Day Midwest on June 5th, 2025.\n\nA testimonial from a Cyber Security Engineer at a FAANG company:\n\n> _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._\n\n## Installation\n\n```bash\npip install boto3-refresh-session\n```\n\n## Usage (STS)\n\nMost users use AWS STS to assume an IAM role and return a set of temporary security credentials. boto3-refresh-session can be used to ensure those temporary credentials refresh automatically.\n\n```python\nimport boto3_refresh_session as brs\n\n# you can pass all of the params normally associated with boto3.session.Session\nprofile_name = \"<your-profile-name>\"\nregion_name = \"us-east-1\"\n...\n\n# as well as all of the params associated with STS.Client.assume_role\nassume_role_kwargs = {\n \"RoleArn\": \"<your-role-arn>\",\n \"RoleSessionName\": \"<your-role-session-name>\",\n \"DurationSeconds\": \"<your-selection>\",\n ...\n}\n\n# as well as all of the params associated with STS.Client, except for 'service_name'\nsts_client_kwargs = {\n \"region_name\": region_name,\n ...\n}\n\n# basic initialization of boto3.session.Session\nsession = brs.RefreshableSession(\n assume_role_kwargs=assume_role_kwargs, # required\n sts_client_kwargs=sts_client_kwargs,\n region_name=region_name,\n profile_name=profile_name,\n ...\n)\n```\n\n## Usage (ECS)\n\nYou can use boto3-refresh-session in an ECS container to automatically refresh temporary security credentials.\n\n```python\nsession = RefreshableSession(\n method=\"ecs\", \n region_name=region_name, \n profile_name=profile_name,\n ...\n)\n```\n\n## Usage (Custom)\n\nIf 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.\n\n```python\n# create (or import) your custom credential method\ndef your_custom_credential_getter(...):\n ...\n return {\n \"access_key\": ...,\n \"secret_key\": ...,\n \"token\": ...,\n \"expiry_time\": ...,\n }\n\n# and pass it to RefreshableSession\nsession = RefreshableSession(\n method=\"custom\",\n custom_credentials_method=your_custom_credential_getter,\n custom_credentials_method_args=...,\n region_name=region_name,\n profile_name=profile_name,\n ...\n)\n```",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple Python package for refreshing the temporary security credentials in a boto3.session.Session object automatically.",
"version": "1.3.18",
"project_urls": {
"Documentation": "https://michaelthomasletts.github.io/boto3-refresh-session/index.html",
"Homepage": "https://github.com/michaelthomasletts/boto3-refresh-session",
"Repository": "https://github.com/michaelthomasletts/boto3-refresh-session"
},
"split_keywords": [
"boto3",
" botocore",
" aws",
" sts",
" ecs",
" credentials",
" token",
" refresh"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bb964c8650abad9580a2be20dd4a7badd2a57900c56eed6badd6d862a141e6eb",
"md5": "01eafbaae12b2a57efebbae91ef39599",
"sha256": "045801c97074f71b4b516ddca0cb7948688f8dc48f6a9206a9a2169399567634"
},
"downloads": -1,
"filename": "boto3_refresh_session-1.3.18-py3-none-any.whl",
"has_sig": false,
"md5_digest": "01eafbaae12b2a57efebbae91ef39599",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 11983,
"upload_time": "2025-07-12T11:45:54",
"upload_time_iso_8601": "2025-07-12T11:45:54.895631Z",
"url": "https://files.pythonhosted.org/packages/bb/96/4c8650abad9580a2be20dd4a7badd2a57900c56eed6badd6d862a141e6eb/boto3_refresh_session-1.3.18-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3a64b4b3c76e2888e5c116e9f0a2714b4375b45d3b1236807f71663a03e763a9",
"md5": "b86127dcd266e39b662caf0807acb9b2",
"sha256": "a10379aa4aee3a216dd881df1ae675d0d27fb72dce970c446f1d5155bd9765c3"
},
"downloads": -1,
"filename": "boto3_refresh_session-1.3.18.tar.gz",
"has_sig": false,
"md5_digest": "b86127dcd266e39b662caf0807acb9b2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 10523,
"upload_time": "2025-07-12T11:45:56",
"upload_time_iso_8601": "2025-07-12T11:45:56.068323Z",
"url": "https://files.pythonhosted.org/packages/3a/64/b4b3c76e2888e5c116e9f0a2714b4375b45d3b1236807f71663a03e763a9/boto3_refresh_session-1.3.18.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 11:45:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "michaelthomasletts",
"github_project": "boto3-refresh-session",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "boto3-refresh-session"
}
JSON
