Credential & Secret Management

Hive provides a robust credential management system designed to handle the long-term secret requirements of autonomous agents. It moves beyond simple environment variables by offering a structured vault for API keys, OAuth2 tokens, and custom authentication schemas, supporting automatic lifecycle management and secure storage.

Core Concepts

The credential system is built around three primary entities:

• CredentialKey: The smallest unit of a secret (e.g., a specific access_token or api_key).
• CredentialObject: A logical container for related keys (e.g., a "GitHub" credential containing both an access_token and a refresh_token).
• CredentialType: A classification that determines how the system interacts with the secret (e.g., OAUTH2 vs. API_KEY).

Security Features

To ensure production-grade security, Hive utilizes:

• SecretStr wrapping: All secret values are wrapped in Pydantic's SecretStr, which masks the value in logs, tracebacks, and console outputs.
• Expiration Tracking: Integrated expires_at fields allow the runtime to preemptively refresh tokens.
• Isolation: Credentials are stored and accessed through a provider interface, abstracting the underlying storage (Local or Vault).

Supported Credential Types

When defining a credential, you must specify its type via the CredentialType enum:

| Type | Description | | :--- | :--- | | API_KEY | Simple static tokens (e.g., OpenAI, Brave Search). | | OAUTH2 | Multi-key credentials with support for access_token and refresh_token. | | BASIC_AUTH | Traditional username and password pairs. | | BEARER_TOKEN | JWTs or other bearer tokens without built-in refresh logic. | | CUSTOM | Flexible structure for user-defined authentication requirements. |

The Credential Object

The CredentialObject is the primary interface for managing secrets within your agent workflows.

from framework.credentials.models import CredentialObject, CredentialType

# Example: Defining a GitHub OAuth credential
github_creds = CredentialObject(
    id="github_production",
    credential_type=CredentialType.OAUTH2,
    provider_id="oauth2_provider",
    auto_refresh=True
)

# Adding keys to the object
github_creds.set_key(
    key_name="access_token",
    value="ghp_xxxx...",
    expires_at=datetime(2025, 1, 1)
)

Key Methods

| Method | Description | | :--- | :--- | | get_key(key_name: str) | Retrieves the raw secret value for the specified key. Returns None if not found. | | set_key(...) | Adds or updates a secret key. Accepts value, expires_at, and optional metadata. | | has_key(key_name: str) | Returns a boolean indicating if the key exists in the object. | | needs_refresh | (Property) Checks if any keys within the object are expired or nearing expiration. |

Lifecycle & Refresh Management

Hive supports automated lifecycle management for secrets that expire. By setting auto_refresh=True and providing a provider_id, the Hive runtime can automatically trigger refresh logic (e.g., using an OAuth2 refresh token to fetch a new access token) before an agent node executes.

if my_credential.needs_refresh:
    # The framework uses the provider_id to locate 
    # the correct logic to update the keys.
    pass

Storage Backends

Hive supports multiple storage backends to balance development ease with production security.

Local Storage (Default)

For local development and testing, Hive stores encrypted JSON blobs in the .hive/credentials directory. This is sufficient for single-user agents or local TUI usage.

Hashicorp Vault Integration

In production environments, Hive integrates with Hashicorp Vault to provide:

• Centralized Secret Management: Secrets are stored in a dedicated secure cluster.
• Audit Logging: Every access to a credential by an agent is logged by Vault.
• Dynamic Injection: Secrets are injected into the agent runtime at execution time and are never persisted to the local disk of the agent host.

Configuration: To enable Vault, configure the following environment variables or runtime settings:

• HIVE_VAULT_ADDR: The URL of your Vault instance.
• HIVE_VAULT_TOKEN: The authentication token (or use standard Vault auth methods).
• HIVE_VAULT_PATH: The KV store path prefix for Hive credentials.

Usage in Agent Nodes

Tools and nodes can access credentials via the AgentRuntime. When a tool requires a secret, it should request it by ID from the credential store rather than expecting it in the tool input, ensuring secrets remain outside of the LLM context window.

# Internal usage example
async def execute_tool(runtime):
    creds = await runtime.credential_store.get("brave_search")
    api_key = creds.get_key("api_key")
    # Use api_key for the request...