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.

from praisonaiagents import Agent
from praisonai import AnthropicManagedAgent, ManagedConfig

managed = AnthropicManagedAgent(config=ManagedConfig(model="claude-sonnet-4-6"))
agent = Agent(name="Integrations", instructions="Call external APIs using vault-stored OAuth tokens.", llm=managed)
agent.start("Summarise my latest calendar events.")

The user stores OAuth credentials in a vault; the managed agent reads them securely when calling external APIs.

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

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

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

Security Principles

• 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"
# )

Vault Organization

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"
)

Error Handling

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

Performance Optimization

• 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

Managed Runtime Protocol

Remote agent runtime with vault integration

Managed Agent Lifecycle

Complete agent, environment, and session management