---
id: boto3-assume
version: "0.2.1"
license: Apache License 2.0
license_treatment: permissive
maintenance: aging
---

# boto3-assume — Easily create boto3 assume role sessions with automatic credential refreshing.

License: permissive · Maintenance: aging · Downloads: 216.2K/mo

## What it is and what it does

boto3-assume is a thin wrapper around boto3 that simplifies the creation of assume-role sessions with built-in credential refreshing. Instead of manually managing STS AssumeRole calls and credential expiration, you pass a source boto3 Session and role details to assume_role(), which returns a new session whose credentials automatically refresh when they expire. The wrapper handles the STS client creation and credential lifecycle internally.

The package is designed for developers who need to work with multiple AWS IAM roles within a single application—particularly in cross-account scenarios or when switching between roles frequently. It reduces boilerplate by eliminating the need to manually track credential expiration times or re-invoke AssumeRole. The underlying mechanism uses boto3's STS client to call assume_role with your specified parameters (RoleArn, RoleSessionName, optional DurationSeconds, tags, etc.) and wraps the resulting credentials in a session that refreshes them transparently.

Use it for:

- Cross-account AWS access: assume a role in another AWS account to access resources without managing separate credentials.
- Multi-role applications: switch between different IAM roles within the same application without manual credential refresh logic.
- Long-running services: maintain assume-role credentials that auto-refresh over hours or days without manual intervention.
- Temporary elevated permissions: assume a higher-privilege role for specific tasks, with credentials automatically expiring after a set duration.
- CI/CD pipelines: assume deployment or testing roles without hardcoding temporary credentials in environment variables.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Wraps boto3 to create AWS IAM assume-role sessions with automatic credential refreshing, eliminating manual credential management when switching roles.

Yes, if you regularly assume AWS IAM roles in boto3 applications. The package eliminates credential-refresh boilerplate and is lightweight (two dependencies). The aging maintenance status (211 days since last release) is a minor concern for a stable, narrow-scope utility, but check whether your Python version (3.10+) and boto3 version are compatible. No known vulnerabilities.

## Install

pip install boto3-assume
uv add boto3-assume
poetry add boto3-assume

## Installing boto3-assume

Before you install: Low install friction with only two runtime dependencies (boto3, botocore). Maintenance status is aging—last release was 211 days ago, though the repository remains active with a recent commit on 2026-01-15.

License in practice: Apache License 2.0 is permissive, allowing commercial use, modification, and distribution with minimal restrictions beyond attribution and liability disclaimers.

Quickstart:

pip install boto3-assume

import boto3
from boto3_assume import assume_role

assume_session = assume_role(
    source_session=boto3.Session(),
    assume_role_kwargs={
        "RoleArn": "arn:aws:iam::123412341234:role/my_role",
        "RoleSessionName": "my-role-session"
    }
)
sts_client = assume_session.client("sts", region_name="us-east-1")

Requires a boto3 Session with automatic credential refreshing already configured; credentials must have permission to assume the target role.

Verify before relying:

- Whether automatic refresh happens transparently on every client call or only when credentials expire.
- Performance overhead compared to creating a standard boto3 session with assume-role credentials.
- Support for cross-account and cross-partition role assumptions beyond standard AWS partitions.

## Package facts

- License: Apache License 2.0 (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: aging
- Downloads: 216.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

boto3 assume role, aws iam role assumption, automatic credential refresh, cross-account aws access, boto3 session wrapper, aws sts assume role, refreshable aws credentials, aws-iam, credential-management

[View on SkillFed](https://skillfed.io/packages/boto3-assume) · [View on PyPI](https://pypi.org/project/boto3-assume/)