Skip to main content

Documentation Index

Fetch the complete documentation index at: https://aivault.moldable.sh/docs/llms.txt

Use this file to discover all available pages before exploring further.

For providers that use OAuth2 (Spotify, QuickBooks, Xero, Reddit, etc.), the initial consent and code exchange happen outside the broker boundary. aivault only handles the refresh/runtime phase.

​
oauth setup

Generate a consent URL for an OAuth2 provider. 
aivault oauth setup \
  --provider google \
  --auth-url https://accounts.google.com/o/oauth2/v2/auth \
  --client-id <client-id> \
  --redirect-uri http://127.0.0.1:8787/callback \
  --scope gmail.readonly
This returns a consent URL — open it in a browser to authorize the application.

​
Options

FlagDescription
--providerProvider name
--auth-urlOAuth2 authorization endpoint
--client-idApplication client ID
--redirect-uriRedirect URI for the callback
--scopeOAuth2 scopes (repeatable)
--stateOptional state parameter for CSRF protection

​
Full OAuth2 lifecycle

1. Generate consent URL
   ┌─────────────────────────────────────────────┐
   │ aivault oauth setup --provider google \      │
   │   --auth-url https://accounts.google.com/... │
   │   --client-id <id> --redirect-uri <uri>      │
   │                                               │
   │ → Returns consentUrl — open in browser        │
   └─────────────────────────────────────────────┘

2. Exchange auth code for tokens (outside aivault)
   ┌─────────────────────────────────────────────┐
   │ Use your own runtime or curl to exchange     │
   │ the auth code for access + refresh tokens.   │
   └─────────────────────────────────────────────┘

3. Store tokens in vault
   ┌─────────────────────────────────────────────┐
   │ aivault secrets create --name SPOTIFY_OAUTH \ │
   │   --value '{"clientId":"...","clientSecret":  │
   │            "...","refreshToken":"..."}'        │
   │                                               │
   │ → Credential auto-provisioned: spotify        │
   └─────────────────────────────────────────────┘

4. Invoke (automatic token refresh)
   ┌─────────────────────────────────────────────┐
   │ aivault invoke spotify/playlists ...         │
   │                                               │
   │ Broker automatically:                         │
   │ → Checks if access_token is expired           │
   │ → Refreshes via token endpoint if needed      │
   │ → Writes new tokens back to vault             │
   │ → Injects Bearer token into request           │
   └─────────────────────────────────────────────┘
The key insight: aivault manages the runtime token refresh automatically. You only need to do the initial consent/exchange once. After that, the broker handles refreshing expired tokens transparently on every invoke. For public/native OAuth clients that use PKCE, omit clientSecret from the secret JSON: 
aivault secrets create --name GOOGLE_GMAIL_OAUTH \
  --value-file /path/to/oauth-secret.json \
  --scope workspace --workspace-id personal
--value-file is preferred for token payloads because the secret value does not appear in the process argument list. Next: Security