Quickstart

import asyncio
from alter_sdk import AlterVault, HttpMethod

async def main():
    vault = AlterVault(
        api_key="alter_key_...",
        caller="my-agent",
    )

    # Open browser → user authorizes → SDK returns connection
    results = await vault.connect(
        providers=["google"],
    )
    print(f"Connected: {results[0].grant_id}")

    # Make API calls with the grant
    response = await vault.request(
        HttpMethod.GET,
        "https://www.googleapis.com/calendar/v3/calendars/primary/events",
        grant_id=results[0].grant_id,
        query_params={"maxResults": "10"},
    )
    events = response.json()

    for event in events.get("items", []):
        print(f"Event: {event['summary']}")

    await vault.close()

asyncio.run(main())

from alter_sdk import AlterVault, CallerType

vault = AlterVault(
    api_key="alter_key_...",              # Required: API key from dashboard
    caller="my-agent",                    # Optional: Caller identity for audit logs
    caller_type=CallerType.AGENT,         # Optional: AGENT (default) or SERVICE
    timeout=30.0,                         # Optional: HTTP timeout in seconds
)

from alter_sdk import AlterVault, HttpMethod

vault = AlterVault(
    api_key="alter_key_...",
    caller="my-agent",
    # Called before every request — return a fresh JWT for the current user.
    # Sync or async callables are both supported.
    user_token_getter=lambda: get_current_user_jwt(),
)

# `provider=` looks up the grant that belongs to the JWT's user — no grant_id needed.
response = await vault.request(
    HttpMethod.GET,
    "https://www.googleapis.com/calendar/v3/calendars/primary/events",
    provider="google",
)

auth_result = await vault.authenticate()
print(auth_result.user_info)  # { sub, email, name, ... } from the IDP

from alter_sdk import AlterVault, HttpMethod

vault = AlterVault(api_key="alter_key_...")  # no user_token_getter

# Start the OAuth flow. With no user_token, the resulting grant is system-principal.
session = await vault.create_connect_session(allowed_providers=["google"])
print("Open this URL to authorize:", session.connect_url)

# After the operator completes OAuth in the browser, look up the new grant.
# Because no user_token_getter is configured, list_grants() returns app-scoped grants.
result = await vault.list_grants(provider_id="google", limit=5)
grant = result.grants[0]
assert grant.principal_type == "system"

response = await vault.request(
    HttpMethod.GET,
    "https://www.googleapis.com/calendar/v3/calendars/primary/events",
    grant_id=grant.grant_id,
)

from alter_sdk.exceptions import (
    ReAuthRequiredError,
    ScopeReauthRequiredError,
    PolicyViolationError,
    TokenRefreshInProgressError,
    GrantNotFoundError,
    AmbiguousGrantError,
)

try:
    # Identity mode — the SDK resolves the grant from the configured
    # user_token_getter. AmbiguousGrantError can only be raised on this
    # path; direct (grant_id=...) mode addresses a single grant.
    response = await vault.request(
        HttpMethod.GET,
        "https://www.googleapis.com/calendar/v3/calendars/primary/events",
        provider="google",
    )
except ScopeReauthRequiredError as e:
    print(f"Scopes changed — user must re-authorize (provider: {e.provider_id}, grant: {e.grant_id})")
except ReAuthRequiredError:
    print("User must re-authorize via Alter Connect")
except PolicyViolationError as e:
    print(f"Access denied by policy: {e.message} (rule: {e.policy_error})")
except TokenRefreshInProgressError as e:
    # Another request is mid-refresh — transient, retry after backoff
    print(f"Token refresh in progress for {e.grant_id} — retry after backoff")
except AmbiguousGrantError as e:
    # JWT identity resolution matched multiple active grants — supply
    # `account` to disambiguate. The matching identifiers are exposed on
    # the exception so the caller can prompt or pick.
    print(f"Multiple grants for {e.provider_id}: {e.account_identifiers}")
except GrantNotFoundError:
    print("User hasn't connected Google yet")

result = await vault.revoke_grant(
    grant_id=grant_id,
    reason="Agent cleanup: stale grant",  # optional; stored in the audit log
)
print(f"Revoked at {result.revoked_at}")

from alter_sdk import AlterVault, GroupPrincipal, UserPrincipal, SystemPrincipal

# Tie the secret to an IDP group — every member with a verified JWT gets access
grant = await vault.create_managed_secret_grant(
    "a1b2c3d4-5e6f-7890-abcd-ef0123456789",
    principal=GroupPrincipal(
        idp_id="idp_xyz",
        external_group_id="okta-group-engineering",
        label="engineering-prod-stripe",
    ),
)

# Tie the secret to a specific end user (validates user_token against the IDP).
# `label` is required so the wallet can render meaningful copy.
grant = await vault.create_managed_secret_grant(
    "a1b2c3d4-5e6f-7890-abcd-ef0123456789",
    principal=UserPrincipal(
        user_token=current_user_jwt,
        label="alice-prod-stripe-readonly",
    ),
)

# Headless system grant — no end-user identity required. `label` is optional
# because system grants typically don't surface in the wallet.
grant = await vault.create_managed_secret_grant(
    "a1b2c3d4-5e6f-7890-abcd-ef0123456789",
    principal=SystemPrincipal(label="cron-stripe-charges"),
)

print(grant.grant_id, grant.principal_type)