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.

Use this for explicit control over which grant backs each call. Common when there’s no end user in the loop (cron jobs, webhook handlers) or for a managed secret. For apps with logged-in users, prefer JWT identity.

​
The pattern

Construct the SDK with no user_token_getter. Read the grant_id from app config or the application database. Pass it explicitly per call. 
from alter_sdk import App, HttpMethod

vault = App(api_key=ALTER_API_KEY)

response = await vault.request(
    HttpMethod.POST,
    "https://api.stripe.com/v1/charges",
    grant_id=STRIPE_GRANT_ID,
    body={"amount": "2000", "currency": "usd"},
)

​
Where grant_id comes from

SourcePage
OAuth flow result (the user just authorized)Headless, Connect.js
Listed from the backendManaging grants
Provisioned in the developer portal (managed secret)Managed Secrets → Issuing grants
Already stored in the application DB or envRead it like any other identifier
grant_id is a UUID. Treat it the same way as any internal foreign key — store it, scope it to the right user/tenant, and pass it through.

​
Listing grants

Show end users their connected accounts, build a multi-tenant management UI, or rotate grants: 
page = await vault.list_grants(provider_id="google", limit=50)
for grant in page.grants:
    print(grant.grant_id, grant.account_identifier, grant.scopes)
The full list/filter API is documented at SDK → Grants.

​
When not to use this

  • Apps with logged-in users → JWT identity (avoid tracking grant_id in application code).
  • Bootstrapping a grant from a CLI → Headless (run vault.connect() and capture the returned grant_id).

​
Multi-tenant scoping

When the same backend serves multiple end users (and JWT identity isn’t in use), make sure each grant_id only flows to code paths authorized to act for that user. Common safeguards:
  • Store grant_id in a row keyed by the application’s internal user ID. Look it up at request time after authenticating the request.
  • Never accept grant_id from untrusted input. A leaked grant_id is enough to use the underlying credential.
  • Log every retrieval with the internal user ID in context={...} so audit queries can correlate Alter’s audit log with the application’s.

​
See also