Skip to main content

​
Overview

Hive includes a credential store for API keys, OAuth tokens, and multi-key secrets. The store is intentionally separate from tool logic:
  • The store keeps and resolves credential values
  • Tools define how those values are injected (headers, params, payloads)
This separation keeps credential handling reusable and predictable.

​
Core Concepts

  • CredentialStore: main API for save/load/refresh/resolve
  • CredentialObject: credential record that can contain multiple keys
  • CredentialStorage: backend interface (encrypted files, env vars, vault, composite)
  • CredentialProvider: lifecycle integration for refresh and validation

​
Quick Start

from framework.credentials import CredentialStore, InMemoryStorage

store = CredentialStore(storage=InMemoryStorage())
store.save_api_key("brave_search", "your-api-key")

api_key = store.get("brave_search")
headers = store.resolve_headers({"X-Subscription-Token": "{{brave_search.api_key}}"})

​
Template Resolution

Use credential templates in request definitions:
  • {{credential_id}} resolves the default key
  • {{credential_id.key_name}} resolves a specific key
Example: 
headers = store.resolve_headers({
    "Authorization": "Bearer {{github_oauth.access_token}}",
    "X-API-Key": "{{brave_search.api_key}}",
})

​
Storage Backends

Use encrypted local storage for production-like local environments:
  • Path default: ~/.hive/credentials
  • Encryption key via HIVE_CREDENTIAL_KEY

​
EnvVar Storage

Use existing environment variables as read-only credentials for compatibility.

​
Composite Storage

Layer storages with fallback behavior, for example encrypted files as primary and env vars as fallback.

​
HashiCorp Vault

Use Vault storage for enterprise secret management.

​
OAuth2 and Auto-Refresh

Credentials can be linked to providers for refresh/validation:
  • Save tokens with provider_id
  • Enable auto_refresh
  • Call store.get(...) and let provider logic refresh when needed

​
Best Practices

  • Use encrypted storage outside test environments
  • Keep provider-specific refresh logic in providers, not tool code
  • Never commit credential values into repositories
  • Add tests for token expiry and refresh paths