Overview
The Hive credentials system provides production-ready credential management with:
- Key-vault structure: Credentials as objects with multiple keys
- Template-based usage:
{{cred.key}} patterns for injection
- Provider system: Extensible lifecycle management (refresh, validate)
- Multiple backends: Encrypted files, env vars, HashiCorp Vault
Quick Start
from framework.credentials import CredentialStore
# Create store with encrypted storage
store = CredentialStore.with_encrypted_storage() # defaults to ~/.hive/credentials
# Get a credential
api_key = store.get("brave_search")
# Resolve templates in headers
headers = store.resolve_headers({
"Authorization": "Bearer {{github_oauth.access_token}}"
})
Class: CredentialStore
Main interface for credential management.
from framework.credentials import CredentialStore, EncryptedFileStorage
store = CredentialStore(
storage=EncryptedFileStorage(
base_path="~/.hive/credentials",
encryption_key=encryption_key
)
)
Constructor
storage
CredentialStorage
required
Storage backend for credentials
providers
dict[str, CredentialProvider]
default:"{}"
Credential providers for lifecycle management
Factory Methods
Create a store with encrypted file storage (recommended)store = CredentialStore.with_encrypted_storage(
base_path="~/.hive/credentials"
)
Create a store using environment variables onlystore = CredentialStore.with_env_vars()
Methods
get()
Get a credential by ID.
cred = store.get("github_oauth")
if cred:
access_token = cred.keys["access_token"].value
The credential object, or None if not found
save_credential()
Save a credential to storage.
from framework.credentials import CredentialObject, CredentialKey
from pydantic import SecretStr
store.save_credential(CredentialObject(
id="my_api",
keys={
"api_key": CredentialKey(
name="api_key",
value=SecretStr("sk-...")
)
}
))
delete_credential()
Delete a credential.
store.delete_credential("my_api")
The credential ID to delete
Resolve template patterns in HTTP headers.
headers = store.resolve_headers({
"Authorization": "Bearer {{github_oauth.access_token}}",
"X-API-Key": "{{brave_search.api_key}}"
})
# Returns: {"Authorization": "Bearer ghp_...", "X-API-Key": "..."}
Headers with template patterns {{cred_id.key_name}}
Headers with resolved values
list_credentials()
List all credential IDs.
cred_ids = store.list_credentials()
print(cred_ids) # ['github_oauth', 'brave_search', ...]
Class: CredentialObject
Represents a credential with multiple keys.
from framework.credentials import CredentialObject, CredentialKey, CredentialType
from pydantic import SecretStr
cred = CredentialObject(
id="github_oauth",
credential_type=CredentialType.OAUTH2,
keys={
"access_token": CredentialKey(
name="access_token",
value=SecretStr("ghp_...")
),
"refresh_token": CredentialKey(
name="refresh_token",
value=SecretStr("ghr_...")
)
},
metadata={
"expires_at": "2024-12-31T23:59:59Z",
"scopes": ["repo", "user"]
}
)
Fields
Unique identifier for the credential
credential_type
CredentialType
default:"CredentialType.API_KEY"
Type: API_KEY, OAUTH2, BASIC_AUTH, BEARER_TOKEN, SSH_KEY, DATABASE, CUSTOM
keys
dict[str, CredentialKey]
required
The credential keys (e.g., api_key, access_token, refresh_token)
metadata
dict[str, Any]
default:"{}"
Additional metadata (expiry, scopes, etc.)
ID of the provider managing this credential
Class: CredentialKey
A single key within a credential.
from framework.credentials import CredentialKey
from pydantic import SecretStr
key = CredentialKey(
name="api_key",
value=SecretStr("sk-..."),
description="API key for authentication"
)
Fields
Key name (e.g., “api_key”, “access_token”)
The secret value (auto-redacted in logs)
Human-readable description
How to use this key (e.g., “Bearer “)
Storage Backends
EncryptedFileStorage
Encrypted file-based storage (recommended for production).
from framework.credentials import EncryptedFileStorage
storage = EncryptedFileStorage(
base_path="~/.hive/credentials",
encryption_key=encryption_key # 32-byte key
)
Base directory for credential files
32-byte encryption key (use generate_and_save_credential_key())
EnvVarStorage
Environment variable storage.
from framework.credentials import EnvVarStorage
storage = EnvVarStorage(
prefix="HIVE_CRED_"
)
prefix
str
default:"'HIVE_CRED_'"
Prefix for environment variables
{prefix}{CRED_ID}_{KEY_NAME} (e.g., HIVE_CRED_GITHUB_OAUTH_ACCESS_TOKEN)
CompositeStorage
Combine multiple storage backends with fallback.
from framework.credentials import CompositeStorage, EncryptedFileStorage, EnvVarStorage
storage = CompositeStorage(
storages=[
EncryptedFileStorage(base_path="~/.hive/credentials"),
EnvVarStorage(prefix="HIVE_CRED_")
]
)
Key Management
generate_and_save_credential_key()
Generate and save an encryption key.
from framework.credentials import generate_and_save_credential_key
key = generate_and_save_credential_key(
key_path="~/.hive/credential.key"
)
key_path
str | Path
default:"'~/.hive/credential.key'"
Path to save the key
The generated 32-byte encryption key
load_credential_key()
Load an existing encryption key.
from framework.credentials import load_credential_key
key = load_credential_key(
key_path="~/.hive/credential.key"
)
key_path
str | Path
default:"'~/.hive/credential.key'"
Path to the key file
Interactive Setup
run_credential_setup_cli()
Interactive CLI for credential setup.
from framework.credentials import run_credential_setup_cli
result = run_credential_setup_cli(
agent_path="path/to/my_agent"
)
Path to the agent requiring credentials
Setup result with success status and configured credentials
Validation
validate_agent_credentials()
Validate that all required credentials are available.
from framework.credentials import validate_agent_credentials
results = validate_agent_credentials(
agent_path="path/to/my_agent",
store=credential_store
)
for result in results:
if result.status == CredentialStatus.MISSING:
print(f"Missing: {result.credential_id}")
Credential store to validate against
results
list[CredentialValidationResult]
Validation results for each required credential
Example: Complete Setup
from framework.credentials import (
CredentialStore,
CredentialObject,
CredentialKey,
CredentialType,
generate_and_save_credential_key,
EncryptedFileStorage
)
from pydantic import SecretStr
# Generate encryption key
key = generate_and_save_credential_key("~/.hive/credential.key")
# Create store
store = CredentialStore(
storage=EncryptedFileStorage(
base_path="~/.hive/credentials",
encryption_key=key
)
)
# Save credentials
store.save_credential(CredentialObject(
id="github_oauth",
credential_type=CredentialType.OAUTH2,
keys={
"access_token": CredentialKey(
name="access_token",
value=SecretStr("ghp_...")
),
"refresh_token": CredentialKey(
name="refresh_token",
value=SecretStr("ghr_...")
)
},
metadata={
"expires_at": "2024-12-31T23:59:59Z",
"scopes": ["repo", "user"]
}
))
# Use credentials
headers = store.resolve_headers({
"Authorization": "Bearer {{github_oauth.access_token}}"
})
print(headers)
# {'Authorization': 'Bearer ghp_...'}