Skip to main content
Vault Manager provides secure storage for OAuth credentials, enabling agents to access external services without exposing secrets.

​
Quick Start

1

Create and Use Vault

Store OAuth credentials and reference in agent configuration.
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)
2

Manage Multiple Vaults

Store and organize credentials for different services.
# 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

ComponentResponsibilitySecurity
VaultManagerCRUD operations on vaultsCredentials never returned
Anthropic APIEncrypted credential storageEnd-to-end encryption
Agent RuntimeSecure credential accessTemporary, session-scoped
External APIsService integrationStandard OAuth flows

​
VaultManager API

​
Core Methods

MethodPurposeReturns
create(provider, credentials, name?)Store new credentialsvault_id: str
list(**kwargs)List vault metadataList[Dict[str, Any]]
retrieve(vault_id)Get vault metadataDict[str, Any]
delete(vault_id)Remove vault permanentlyNone
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

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

# 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

# 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

# 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

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

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

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
# 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:
# 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:
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

Managed Runtime Protocol

Remote agent runtime with vault integration

Managed Agent Lifecycle

Complete agent, environment, and session management