> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Managed Vault
> Secure OAuth credentials storage for managed agent integrations
Vault Manager provides secure storage for OAuth credentials, enabling agents to access external services without exposing secrets.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Vault Management Flow"
A[🔑 OAuth Credentials] --> B[🏦 Create Vault]
B --> C[💾 Secure Storage]
C --> D[🤖 Agent Access]
D --> E[🌐 External API]
F[🗂️ List Vaults] --> G[📋 Vault Metadata]
H[🗑️ Delete Vault] --> I[🔒 Cleanup]
end
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef vault fill:#8B0000,stroke:#7C90A0,color:#fff
classDef storage fill:#189AB4,stroke:#7C90A0,color:#fff
classDef access fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef api fill:#10B981,stroke:#7C90A0,color:#fff
class A input
class B,F,H vault
class C,G,I storage
class D access
class E api
```
## Quick Start
Store OAuth credentials and reference in agent configuration.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai import AnthropicManagedAgent, ManagedConfig
managed = AnthropicManagedAgent(config=ManagedConfig(
model="claude-sonnet-4-6",
system="You are a GitHub integration assistant."
))
# Create vault for GitHub access token
vault_id = managed.vaults.create(
provider="github",
credentials={"access_token": "ghp_abc123..."},
name="my-github-token"
)
# Use vault in agent configuration
config = ManagedConfig(
vault_ids=[vault_id],
tools=[{"type": "github_toolkit"}]
)
# Agent can now access GitHub API securely
agent_id = await managed.create_agent(config)
```
Store and organize credentials for different services.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Create vaults for different services
github_vault = managed.vaults.create(
provider="github",
credentials={"access_token": "ghp_..."},
name="github-prod"
)
slack_vault = managed.vaults.create(
provider="slack",
credentials={"access_token": "xoxb-..."},
name="slack-workspace"
)
# Use multiple vaults in configuration
config = ManagedConfig(
vault_ids=[github_vault, slack_vault],
tools=[
{"type": "github_toolkit"},
{"type": "slack_toolkit"}
]
)
```
***
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant VaultManager
participant AnthropicAPI
participant Agent
participant ExternalAPI
User->>VaultManager: create("github", credentials)
VaultManager->>AnthropicAPI: Store encrypted credentials
AnthropicAPI-->>VaultManager: vault_id
VaultManager-->>User: vault_id
User->>Agent: Configure with vault_ids
Agent->>AnthropicAPI: Request vault access
AnthropicAPI->>Agent: Provide decrypted credentials
Agent->>ExternalAPI: Make authenticated requests
ExternalAPI-->>Agent: API responses
```
| Component | Responsibility | Security |
| ----------------- | ---------------------------- | -------------------------- |
| **VaultManager** | CRUD operations on vaults | Credentials never returned |
| **Anthropic API** | Encrypted credential storage | End-to-end encryption |
| **Agent Runtime** | Secure credential access | Temporary, session-scoped |
| **External APIs** | Service integration | Standard OAuth flows |
***
## VaultManager API
### Core Methods
| Method | Purpose | Returns |
| -------------------------------------- | ------------------------ | ---------------------- |
| `create(provider, credentials, name?)` | Store new credentials | `vault_id: str` |
| `list(**kwargs)` | List vault metadata | `List[Dict[str, Any]]` |
| `retrieve(vault_id)` | Get vault metadata | `Dict[str, Any]` |
| `delete(vault_id)` | Remove vault permanently | `None` |
`retrieve()` and `list()` only return metadata (id, provider, name, timestamps).
Actual credentials are never exposed and can only be accessed by agents during session runtime.
### Accessing VaultManager
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai import AnthropicManagedAgent
managed = AnthropicManagedAgent(config=config)
# Access vault manager (lazy-initialized)
vault_manager = managed.vaults
# Perform operations
vault_id = vault_manager.create(provider, credentials)
vaults = vault_manager.list()
vault_manager.delete(vault_id)
```
***
## Supported Providers
### GitHub Integration
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# GitHub personal access token
vault_id = managed.vaults.create(
provider="github",
credentials={"access_token": "ghp_1234567890abcdef"},
name="github-readonly"
)
# GitHub App installation token
vault_id = managed.vaults.create(
provider="github",
credentials={
"access_token": "ghs_1234567890abcdef",
"installation_id": "12345"
},
name="github-app-prod"
)
```
### Slack Integration
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Slack bot token
vault_id = managed.vaults.create(
provider="slack",
credentials={"access_token": "xoxb-1234-5678-abcdef"},
name="slack-bot"
)
# Slack user token
vault_id = managed.vaults.create(
provider="slack",
credentials={"access_token": "xoxp-1234-5678-abcdef"},
name="slack-user"
)
```
### Custom Provider
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Custom OAuth provider
vault_id = managed.vaults.create(
provider="custom-api",
credentials={
"access_token": "at_abc123",
"refresh_token": "rt_def456",
"expires_at": "2024-12-31T23:59:59Z"
},
name="custom-integration"
)
```
***
## Common Patterns
### Vault Lifecycle Management
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
class VaultManager:
def __init__(self, managed_agent):
self.managed = managed_agent
self.vault_cache = {}
def ensure_github_vault(self, token: str) -> str:
"""Create or reuse GitHub vault."""
if "github" not in self.vault_cache:
vault_id = self.managed.vaults.create(
provider="github",
credentials={"access_token": token},
name="github-default"
)
self.vault_cache["github"] = vault_id
return self.vault_cache["github"]
def cleanup_old_vaults(self):
"""Remove unused vaults."""
vaults = self.managed.vaults.list()
for vault in vaults:
if self.is_vault_unused(vault["id"]):
self.managed.vaults.delete(vault["id"])
```
### Multi-Environment Credentials
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
def setup_environment_vaults(env: str):
"""Configure vaults based on environment."""
config = get_env_config(env)
vaults = []
if config.get("github_token"):
vault_id = managed.vaults.create(
provider="github",
credentials={"access_token": config["github_token"]},
name=f"github-{env}"
)
vaults.append(vault_id)
if config.get("slack_token"):
vault_id = managed.vaults.create(
provider="slack",
credentials={"access_token": config["slack_token"]},
name=f"slack-{env}"
)
vaults.append(vault_id)
return vaults
# Use in agent configuration
prod_vaults = setup_environment_vaults("production")
config = ManagedConfig(vault_ids=prod_vaults)
```
### Vault Rotation
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
async def rotate_github_token(old_vault_id: str, new_token: str):
"""Rotate GitHub token safely."""
# Create new vault
new_vault_id = managed.vaults.create(
provider="github",
credentials={"access_token": new_token},
name="github-rotated"
)
# Test new vault by creating test session
test_config = ManagedConfig(vault_ids=[new_vault_id])
try:
agent_id = await managed.create_agent(test_config)
# If successful, update production config
await update_production_vaults(old_vault_id, new_vault_id)
# Clean up old vault
managed.vaults.delete(old_vault_id)
except Exception as e:
# Rollback: delete test vault
managed.vaults.delete(new_vault_id)
raise e
```
***
## Best Practices
* **Minimal Scope**: Use tokens with least privileges needed
* **Environment Separation**: Different vaults for prod/staging/dev
* **Regular Rotation**: Refresh tokens periodically
* **Access Auditing**: Monitor vault usage and access patterns
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Good: Minimal scope token
vault_id = managed.vaults.create(
provider="github",
credentials={"access_token": "ghp_readonly_repo_scope"},
name="github-read-only"
)
# Avoid: Overprivileged token
# vault_id = managed.vaults.create(
# provider="github",
# credentials={"access_token": "ghp_admin_all_orgs"},
# name="github-admin"
# )
```
Use descriptive names and consistent naming conventions:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Good naming convention
naming_pattern = f"{provider}-{environment}-{scope}"
github_prod_read = managed.vaults.create(
provider="github",
credentials={"access_token": token},
name="github-prod-readonly"
)
slack_dev_bot = managed.vaults.create(
provider="slack",
credentials={"access_token": token},
name="slack-dev-bot"
)
```
Handle vault operations failures gracefully:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
try:
vault_id = managed.vaults.create(provider, credentials)
except Exception as e:
logger.error(f"Failed to create vault: {e}")
# Fallback to alternative authentication
# or graceful degradation
try:
vaults = managed.vaults.list()
except Exception as e:
logger.error(f"Failed to list vaults: {e}")
# Use cached vault IDs or prompt for manual input
```
* Cache vault IDs locally to avoid repeated API calls
* Batch vault operations when possible
* Clean up unused vaults regularly
* Use meaningful names for easier vault discovery
***
## Related
Remote agent runtime with vault integration
Complete agent, environment, and session management