Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.alterauth.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Use AWS credentials to make authenticated API calls through Alter Vault without exposing your API keys in code. The SDK computes the full AWS Signature Version 4 (SigV4) signature automatically. Two ways to call AWS services:
  • vault.request() — works in both Python and TypeScript. No AWS SDK dependency; the SDK handles SigV4 signing internally.
  • vault.boto3_client() — Python only. Returns a native boto3 service client so you can use the familiar boto3 API (e.g., client.list_objects_v2(Bucket="...")), with every call routed through Alter Vault for credential management, policy enforcement, and audit logging.
PropertyValue
Provider IDaws
CategoryCloud
Credential TypeAWS SigV4
Required CredentialsAccess Key ID + Secret Access Key
Region / ServiceAuto-detected from request URL

​
Step 1: Get Your Credentials

1

Log in to the AWS Console

Log in to the AWS Console at console.aws.amazon.com.
2

Go to IAM and Users

Go to IAM, then Users and select or create a user with least-privilege permissions at console.aws.amazon.com/iam/home#/users.
3

Create access key

Open the user’s Security Credentials tab and click ‘Create access key’.
4

Copy the Access Key ID

Copy the Access Key ID for the credential field.
5

Copy the Secret Access Key

Copy the Secret Access Key for the Secret Access Key field.
Never share your credentials publicly. Store them securely and only enter them in the Alter Vault Developer Portal.

​
Step 2: Add to Alter Vault

1

Open the Developer Portal

Go to portal.alterauth.com and navigate to your app.
2

Add AWS

Go to Managed Secrets > Add Provider > AWS.
3

Enter your credentials

Paste your Access Key ID and Secret Access Key. That’s it — no region or service configuration needed.
4

Save

Click Save. You’ll receive a grant_id to use with the SDK.

​
Using in Code

A single AWS credential works across any AWS service. Just pass the standard AWS endpoint URL — the SDK detects the region and service from the hostname and signs the request automatically.

​
Option A: vault.request() (Python & TypeScript)

Use vault.request() when you want a lightweight approach with no AWS SDK dependency. The SDK computes SigV4 signatures internally using standard cryptographic libraries. 
from alter_sdk import AlterVault, HttpMethod

async with AlterVault(
    api_key="alter_key_...",
    caller="my-agent",
) as vault:
    # S3
    response = await vault.request(
        HttpMethod.GET,
        "https://s3.us-east-1.amazonaws.com/my-bucket/my-key",
        grant_id="YOUR_GRANT_ID",
    )

    # Bedrock (same credential, different service and region)
    response = await vault.request(
        HttpMethod.POST,
        "https://bedrock-runtime.us-west-2.amazonaws.com/model/anthropic.claude-3-5-sonnet-20241022-v2:0/invoke",
        grant_id="YOUR_GRANT_ID",
        json={"prompt": "Hello"},
    )

    # Lambda
    response = await vault.request(
        HttpMethod.POST,
        "https://lambda.eu-west-1.amazonaws.com/2015-03-31/functions/my-func/invocations",
        grant_id="YOUR_GRANT_ID",
        json={"key": "value"},
    )

​
Option B: vault.boto3_client() (Python only)

Python only. This feature is not available in the TypeScript SDK. TypeScript users should use vault.request() above.
If you prefer the native boto3 API, vault.boto3_client() returns a standard boto3 service client. Every call made through that client is automatically routed through Alter Vault for credential retrieval, SigV4 signing, policy enforcement, and audit logging. You get the full boto3 experience (response parsing, pagination, error types like ClientError) without managing AWS credentials in your code. Install the optional AWS extra: 
pip install 'alter-sdk[aws]'

import asyncio
from alter_sdk import AlterVault

async def main():
    async with AlterVault(
        api_key="alter_key_...",
        caller="my-agent",
    ) as vault:
        # Create a boto3 S3 client routed through Alter Vault
        s3 = await vault.boto3_client(
            "s3",
            grant_id="YOUR_GRANT_ID",
            region_name="us-east-1",
            reason="Listing objects for data pipeline",
        )

        # Use familiar boto3 methods -- must run in a thread
        response = await asyncio.to_thread(
            s3.list_objects_v2, Bucket="my-bucket", MaxKeys=10,
        )
        for obj in response.get("Contents", []):
            print(f"{obj['Key']} ({obj['Size']} bytes)")

        # Same credential, different service
        dynamodb = await vault.boto3_client(
            "dynamodb",
            grant_id="YOUR_GRANT_ID",
            region_name="us-east-1",
        )
        await asyncio.to_thread(
            dynamodb.put_item,
            TableName="MyTable",
            Item={"pk": {"S": "key1"}, "data": {"S": "value1"}},
        )

asyncio.run(main())
boto3 methods are synchronous, so you must call them via asyncio.to_thread() from async code. Each boto3 call triggers a full Alter Vault request cycle (token retrieval, SigV4 signing, audit log), so policy enforcement and audit logging happen on every AWS API call.
boto3_client() parameters:
ParameterTypeDefaultDescription
service_namestr(required)AWS service ("s3", "dynamodb", "bedrock-runtime", etc.)
grant_idstr(required)Grant ID from the Developer Portal
region_namestr"us-east-1"AWS region
timeoutfloatclient timeoutPer-request timeout in seconds
reasonstrNoneAudit reason applied to all calls from this client
contextdictNonePer-request identity context for audit correlation (e.g., {"tool": "s3_list", "agent": "data-pipeline"})
Error handling works natively — boto3 raises botocore.exceptions.ClientError for AWS errors (e.g., NoSuchBucket, AccessDenied), just like a regular boto3 client. Alter Vault-level errors (closed client, network issues) raise AlterSDKError.
Responses are fully buffered in memory. For large payloads (e.g., s3.get_object() on multi-GB files), use vault.request() with httpx streaming instead.

​
Supported URL Patterns

The SDK auto-detects region and service from these AWS hostname formats:
PatternExampleDetected
Standards3.us-east-1.amazonaws.comservice=s3, region=us-east-1
Hyphenated servicebedrock-runtime.us-west-2.amazonaws.comservice=bedrock-runtime, region=us-west-2
S3 virtual-hostedmy-bucket.s3.us-west-2.amazonaws.comservice=s3, region=us-west-2
PrivateLink (regional)vpce-xxx.monitoring.us-east-2.vpce.amazonaws.comservice=monitoring, region=us-east-2
PrivateLink (zonal)vpce-xxx-us-east-2c.monitoring.us-east-2.vpce.amazonaws.comservice=monitoring, region=us-east-2
GovClouds3.us-gov-west-1.amazonaws.comservice=s3, region=us-gov-west-1
For non-AWS custom domains (e.g., a LocalStack endpoint or custom proxy), the SDK cannot auto-detect region and service. Contact support if you need to configure these explicitly.

​
Notes

  • One credential, many services — a single IAM access key can call S3, Lambda, Bedrock, DynamoDB, CloudWatch, and any other AWS service. The SDK signs each request with the correct service and region from the URL.
  • No AWS SDK dependency for vault.request() — the SDK computes SigV4 signatures using only standard cryptographic libraries. You do not need boto3 (Python) or the AWS SDK (Node.js) to use vault.request().
  • Optional boto3 integration (Python only) — if you prefer native boto3 methods and response types, install alter-sdk[aws] and use vault.boto3_client(). See Option B above.
  • Least-privilege IAM — always create credentials on an IAM user or role with only the permissions your application needs. Never use root account access keys.
  • Credential rotation — when you rotate your AWS access key, update it in the Developer Portal. All connections using that secret will immediately use the new key.