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.

​
How Alter Vault Works

Alter Vault is the credential and authorization layer for AI agents that serve multiple users across multiple services. It stores OAuth tokens and API credentials in an encrypted vault, enforces identity-aware policies on every access, and logs every action with full actor context.

​
Two Paths, One API

Alter Vault supports two types of credentials, both accessed through the same vault.request() method:
  • OAuth Connections — for third-party services where users authorize access (Google, Slack, GitHub)
  • Managed Secrets — for internal APIs where credentials are already available (API keys, service tokens)

​
Zero Credential Exposure

Application code never sees or stores credentials. Here is what happens instead:
1

Connect or Store

OAuth: User authorizes through Alter Connect UI. Managed Secrets: Developer stores credentials via the Developer Portal.
2

Encrypt & Store

All credentials are encrypted (AES-256-GCM) and stored in a secure vault
3

Call vault.request()

The SDK retrieves and injects credentials into API calls automatically
4

Automatic Management

OAuth tokens refresh before expiring. Managed secrets are injected with the correct header format.

​
Security

​
Encryption

  • AES-256-GCM encryption for all stored tokens
  • TLS 1.3 for all data in transit
  • Hardware security modules for key management

​
Access Control

  • API key authentication for backend services
  • Session tokens for frontend (never expose API keys)
  • Built-in policies — time-based access, IP allowlist, connection TTL
  • Custom policies — URL restrictions, HTTP method restrictions, rate limiting, and rules tied to user or actor identity. See Security Policies.
  • Fail-closed design — if the policy service is unavailable, all token access is denied

​
Compliance

  • SOC 2 Type II certified
  • HIPAA compliant infrastructure
  • GDPR compliant with data residency options
  • PCI DSS Level 1 for payment integrations

​
Grant ID: The Universal Handle

Every credential in Alter Vault has a unique grant_id (UUID). Usage is identical via vault.request() regardless of credential type. The key difference is where the grant_id comes from:
Credential TypeWhere grant_id Comes FromWho Creates It
OAuthonSuccess callback when end user completes OAuth via Alter ConnectEnd user (by logging into Google, Slack, etc.)
Managed SecretDeveloper Portal when storing a credentialDeveloper (via portal UI)
# OAuth grant — grant_id from end user completing Alter Connect
# (stored in your DB, mapped to your user)
oauth_grant_id = db.get_grant(user_id="alice", provider="google")
response = await vault.request(
    HttpMethod.GET,
    "https://www.googleapis.com/calendar/v3/calendars/primary/events",
    grant_id=oauth_grant_id,
)

# Managed secret — grant_id from Developer Portal
# (stored in your config/env vars, same for all users)
response = await vault.request(
    HttpMethod.GET,
    "https://api.internal.com/v1/loyalty/points",
    grant_id=os.environ["LOYALTY_API_GRANT_ID"],
)
OAuth grants are per-user — each end user who authorizes gets their own grant_id. Managed secrets are per-service — one credential is stored and all backend code shares the same grant_id.

​
Connection Deduplication

Alter Vault automatically prevents duplicate OAuth grants for the same account. When a user re-authorizes, the existing connection is updated instead of creating a duplicate.
  • Search by the OAuth account identifier (email, sub, or ID from the provider)
  • If found, update the existing connection with fresh tokens
  • If not found, create a new connection and return the new grant_id
If a user re-authorizes with the same OAuth account, the existing connection is updated. The grant_id remains the same.

​
Custom Schemas

Add structured data to any OAuth connection: 
{
  "sync_preferences": {
    "calendar": {
      "enabled": true,
      "frequency": "hourly"
    },
    "email": {
      "enabled": false
    }
  }
}
Use cases:
  • Sync settings - Which data to sync, how often
  • User preferences - Per-connection configuration
  • Metadata - Labels, tags, categories
  • Mapping - Link to internal records

​
Audit Logs

All activity is logged automatically, including token access, connection changes, API calls, and admin actions. View, filter, and export logs from the Developer Portal. AI agents are tracked with full context (actor name, run ID, thread ID). See the Audit Logs guide for details on viewing and exporting logs.

​
Performance

Token Retrieval

Less than 10ms for cached tokens

Availability

99.99% uptime SLA

Scale

Millions of tokens/day

​
Credential Management

Alter Vault handles the entire credential lifecycle:

​
Automatic

  • ✅ Store credentials securely — Encrypted at rest (AES-256-GCM)
  • ✅ Refresh OAuth tokens before expiry — No failed API calls
  • ✅ Inject the right header — Bearer, API Key, Basic Auth — automatic
  • ✅ Enforce policies — Time-based and IP restrictions on every access
  • ✅ Retry on failure — Automatic error recovery
  • ✅ Audit all access — Complete compliance trail for both OAuth and managed secrets

​
Eliminated

  • ❌ Store tokens or API keys in the application database
  • ❌ Implement refresh logic
  • ❌ Construct auth headers manually
  • ❌ Manage encryption keys
  • ❌ Build retry mechanisms

​
Architecture Benefits

Tokens are never handled directly by application code, eliminating the risk of token leaks, database breaches, or accidental exposure in logs.
Alter Vault carries SOC 2 and HIPAA certifications, reducing the compliance burden for applications built on top of it.
One integration with Alter Vault provides access to 100+ OAuth providers without learning each API.
When Google changes their OAuth flow or Slack updates their API, Alter Vault handles it. Application code does not change.

​
Integration Example

The complete flow in practice:

​
1. Frontend: User Connects (OAuth)

// User clicks "Connect Google" — your backend creates a session (no user_id needed)
const { session_token } = await fetch('/api/session').then(r => r.json());
await alterConnect.open({
  token: session_token,
  onSuccess: (connections) => {
    // User completed OAuth! Each connection has a grant_id.
    // Store these in your database, mapped to your user.
    for (const conn of connections) {
      saveToDb(currentUser.id, conn.grant_id, conn.provider);
    }
  }
});

​
2. Backend: Use the Connection

from alter_sdk import AlterVault, HttpMethod

vault = AlterVault(
    api_key="alter_key_...",
    caller="my-service",
)

# OAuth: grant_id from your DB (stored when user completed Alter Connect)
grant_id = db.get_grant(user_id="alice", provider="google")
response = await vault.request(
    HttpMethod.GET,
    "https://www.googleapis.com/calendar/v3/calendars/primary/events",
    grant_id=grant_id,
)
events = response.json()

# Managed secret: grant_id from Developer Portal (stored in your config)
response = await vault.request(
    HttpMethod.GET,
    "https://api.internal.com/v1/loyalty/points",
    grant_id=os.environ["LOYALTY_API_GRANT_ID"],
)
That’s it. No token handling, no refresh logic, no storage concerns.

​
Getting Started

Quick Start

Connect a first integration in 5 minutes

Audit Logs

Compliance and observability

Developer Portal

Configure OAuth providers