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.

from alter_sdk import App, HttpMethod

​
request()

Make a token-injected request to a provider API. The most common SDK call.

​
Signature

async def request(
    method: HttpMethod | str,
    url: str,
    *,
    grant_id: str | None = None,
    provider: str | None = None,
    account: str | None = None,
    json: Any = None,
    body: bytes | str | None = None,
    extra_headers: dict[str, str] | None = None,
    query_params: dict[str, str] | None = None,
    path_params: dict[str, str] | None = None,
    reason: str | None = None,
    context: dict[str, str] | None = None,
    user_token: str | None = None,
) -> httpx.Response

​
Parameters

NameTypeDescription
methodHttpMethod | strHTTP method (required).
urlstrFull upstream URL (required).
grant_idstr | NoneExplicit grant. Mutually exclusive with provider.
providerstr | NoneResolves to a grant via user_token_getter. Requires JWT mode.
accountstr | NoneDisambiguator when a user has multiple accounts on one provider.
jsonAny | NoneJSON-serialized body.
bodybytes | str | NoneRaw body.
extra_headersdict[str, str] | NoneAdditional headers (Auth header is set by the SDK).
query_params, path_paramsdict | NoneTemplated URL inputs.
reasonstr | NoneHuman-readable explanation, surfaces in audit logs.
contextdict[str, str] | NonePer-call audit metadata.
user_tokenstr | NonePer-call JWT override.

​
Returns

An httpx.Response. Adds a retry_info: RetryInfo \| None attribute carrying retry metadata from this call.

​
Raises

GrantNotFoundError, GrantExpiredError, GrantRevokedError, AmbiguousGrantError, NoDelegatedGrantError, PolicyViolationError, ScopeReauthRequiredError, ProviderAPIError, NetworkError. See Errors.

​
Example

response = await vault.request(
    HttpMethod.POST,
    "https://api.openai.com/v1/chat/completions",
    grant_id=OPENAI_GRANT_ID,
    json={"model": "gpt-4", "messages": [{"role": "user", "content": "hi"}]},
    context={"tool": "summarize"},
)
print(response.status_code, response.json())

​
proxy_request()

Forwards an HTTP exchange through the Alter backend. Use when the call must run server-side (AWS SigV4 with role assumption, approval-gated calls, backend rate limiting).

​
Signature

async def proxy_request(
    method: HttpMethod | str,
    url: str,
    *,
    grant_id: str,
    json_body: Any = None,
    headers: dict[str, str] | None = None,
    query_params: dict[str, Any] | None = None,
    reason: str | None = None,
) -> ApprovalResult | PendingApproval
Auth headers (Authorization, Cookie, x-api-key, x-amz-security-token) are forbidden — the backend injects credentials at execution time.

​
Returns

  • ApprovalResult if the call ran inline. The body is base64-encoded on body_b64 — decode with body_text() / body_json() / body_bytes().
  • PendingApproval if policy required human approval. Pass the approval_id to await_approval(). See Approvals.

​
Example

result = await vault.proxy_request(
    HttpMethod.POST,
    "https://api.example.com/v1/refunds",
    grant_id=GRANT_ID,
    json_body={"amount": 1000},
    reason="Customer ticket #4421",
)

​
boto3_client()

Returns a boto3 service client whose every call is signed with vault-stored AWS credentials. Python only.

​
Signature

async def boto3_client(
    service_name: str,
    *,
    grant_id: str,
    region_name: str | None = None,
    timeout: float | None = None,
    reason: str | None = None,
    context: dict[str, str] | None = None,
) -> Any

​
Example

s3 = await vault.boto3_client("s3", grant_id=AWS_GRANT_ID, region_name="us-west-2")
result = s3.list_objects_v2(Bucket="my-bucket")
The returned client behaves like a real boto3 client; AWS credentials never enter the process environment.

​
See also