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.

python

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.

Diagram

Quick Start

Create and Use Vault

Store OAuth credentials and reference in agent configuration.

python

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)

Manage Multiple Vaults

Store and organize credentials for different services.

python

# 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

Diagram

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`

Accessing VaultManager

python

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

# 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

# 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

# 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

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

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

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

python

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

python

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

python

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

Managed Runtime Protocol

Remote agent runtime with vault integration

Managed Agent Lifecycle

Complete agent, environment, and session management

Managed Vault

Quick Start

How It Works

VaultManager API

Core Methods

Accessing VaultManager

Supported Providers

GitHub Integration

Slack Integration

Custom Provider

Common Patterns

Vault Lifecycle Management

Multi-Environment Credentials

Vault Rotation

Best Practices

Related