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, Agent

​
list_grants()

Available on both App and Agent. The App variant accepts an optional provider_id filter; the Agent variant does not.

​
Signature

# App
async def list_grants(
    *,
    provider_id: str | None = None,
    limit: int = 100,
    offset: int = 0,
) -> UnifiedGrantListResult

# Agent
async def list_grants(
    *,
    limit: int = 100,
    offset: int = 0,
) -> UnifiedGrantListResult

​
Returns

UnifiedGrantListResult with:
  • grants: list[OAuthGrantItem | ManagedSecretGrantItem] — discriminate on grant_kind.
  • total: int, limit: int, offset: int, has_more: bool.

​
Example

page = await app.list_grants(provider_id="google", limit=50)
for grant in page.grants:
    if grant.grant_kind == "oauth":
        print(grant.grant_id, grant.account_identifier, grant.scopes)

​
create_managed_secret_grant()

Available on App (any principal) and Agent (self only).

​
Signature

async def create_managed_secret_grant(
    managed_secret_id: str,
    *,
    principal: Principal,
    grant_policy: dict[str, Any] | None = None,
) -> CreateGrantResult
grant_policy accepts expires_at, max_ttl_seconds, and default_ttl_seconds. See GrantPolicyInput.

​
Returns

CreateGrantResult with grant_id, principal_type, label, created_at.

​
Raises

PolicyViolationError, AlterValueError.

​
Example

from alter_sdk import UserPrincipal

result = await app.create_managed_secret_grant(
    managed_secret_id="ms_abc123",
    principal=UserPrincipal(user_token=alice_jwt, label="alice-prod-stripe"),
)
print(result.grant_id)
See Managed Secrets → Issuing grants for the full pattern.

​
revoke_grant()

App only.

​
Signature

async def revoke_grant(
    grant_id: str,
    *,
    reason: str | None = None,
) -> RevokeGrantResult

​
Returns

RevokeGrantResult with success, message, grant_id, revoked_at.

​
Raises

GrantNotFoundError, GrantRevokedError (already revoked), PolicyViolationError.

​
Example

result = await app.revoke_grant("grant_xyz", reason="user offboarded")
print(result.revoked_at)

​
revoke_delegation()

App.revoke_delegation(grant_id, agent_id) — operator path. Agent.revoke_delegation(grant_id) — agent self-revoke.

​
Signatures

# App
async def revoke_delegation(grant_id: str, agent_id: str) -> None

# Agent
async def revoke_delegation(grant_id: str) -> None

​
Behavior

Removes the agent’s access path on the grant. The underlying user grant is unchanged. To revoke the underlying grant, call revoke_grant() instead.

​
Example

# Operator removes a specific agent's access on a grant
await app.revoke_delegation("grant_xyz", "agent_research_bot")

# Agent self-revoke
await agent.revoke_delegation("grant_xyz")

​
See also