A grant is a stored authorization to call a provider on behalf of a principal. Every Alter call passes through a grant. A grant is identified by a UUID (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.
grant_id), refers to (but does not contain) the encrypted credential in the vault, and is revocable independently of the underlying credential.
How a grant is created
Two creation paths:- OAuth grants — created when an end user completes the OAuth flow at a provider (via Alter Connect,
app.connect(), or a redirect flow). See Connections. - Managed-secret grants — created when an operator binds a stored credential to a principal (via the developer portal or
app.create_managed_secret_grant()). See Managed secrets.
grant_id, both reach the same app.request() method.
Principals
A grant is owned by a principal — the who the grant belongs to. Four kinds:| Principal | What it represents | Created by |
|---|---|---|
| User | An end user authenticated via the app’s identity provider | OAuth flow, or operator binds a managed secret to one user |
| Group | A set of users defined in the identity provider | Operator binds a managed secret to an IDP group |
| System | The app itself — no human or agent | Operator provisions a managed secret with no principal binding |
| Agent | A named, operator-provisioned workload identity | Operator binds a managed secret to an agent |
Credential type vs principal type
Credential type (OAuth vs managed secret) and principal type (user/group/system/agent) are independent axes. A user-principal grant can be backed by either an OAuth credential or a managed secret. The SDK call site is the same.| Credential | Can back which principals |
|---|---|
| OAuth | User |
| Managed secret | User, Group, System, or Agent |
Grant lifecycle
- Created —
status = active. - Used — every successful
app.request()updateslast_used_at. - Expired — OAuth grants auto-refresh; managed-secret grants stay valid until rotated.
- Revoked — by the end user (in the Wallet), by an operator (in the portal or via SDK), or by policy (TTL elapses, scope mismatch detected).
GrantRevokedError on the next call.
What’s next
- Connections — the OAuth flavor.
- Managed secrets — the operator-provisioned flavor.
- Identity resolution — how the SDK picks a grant at call time.
- Delegation — sharing a user’s grant with an agent.