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.

Identity resolution is how the SDK decides which grant backs a vault.request() call. Three modes. They appear in this order everywhere in these docs because that’s the order to consider them in:
  1. JWT — recommended for apps with an IDP and logged-in users
  2. grant_id — for scripts, batch jobs, and managed secrets
  3. Headless — for CLIs, notebooks, and agents bootstrapping their own grants
The same vault.request() method serves all three. Only the wiring differs. Configure an Identity Provider, pass a user_token_getter at construction, and the SDK resolves the user’s grant from their JWT on every call. 
vault = App(
    api_key=ALTER_API_KEY,
    user_token_getter=lambda: get_jwt_from_request(),
)

# No grant_id — the backend resolves Alice's Google grant from her JWT.
response = await vault.request("GET", url, provider="google")
When to use: any flow where a logged-in user is the reason for the call. SaaS products, agentic apps with a user session, anything that already has a JWT in scope. Why it’s the default: the app stops tracking grant_id in its own database. Deprovisioning a user in the IDP automatically locks them out of grants they own. Full setup →

​
2. grant_id — for scripts, batch jobs, and managed secrets

Pass an explicit grant_id per call. Use this when:
  • The call has no end user (cron jobs, webhook handlers).
  • A managed secret (developer-owned credential) is in use.
  • Explicit control over which grant a request uses is needed.
vault = App(api_key=ALTER_API_KEY)

response = await vault.request("GET", url, grant_id=STRIPE_GRANT_ID)
Full setup →

​
3. Headless — for CLIs, notebooks, and agent bootstrap

vault.connect() and vault.authenticate() open a browser, walk through OAuth, and return a grant_id usable immediately. No frontend, no callback URL. 
vault = App(api_key=ALTER_API_KEY)
results = await vault.connect(providers=["github"])
grant_id = results[0].grant_id
When to use: local scripts, Jupyter notebooks, server-side agents bootstrapping a long-lived grant, the First 5 Minutes walkthrough. Full setup →

​
Picking one — the short version

Is there a logged-in user with a JWT?
├── Yes → JWT
└── No  → Is a grant_id already available?
         ├── Yes → grant_id
         └── No  → Headless (vault.connect())
Modes can be mixed in one app — different SDK instances for different code paths. What’s not allowed is combining an Agent API key with a JWT in the same request; that combination is rejected. See Agents → Overview.

​
See also