Skip to main content

​
Overview

Aden can manage OAuth authorization and refresh centrally, while Hive keeps a local encrypted cache for runtime usage. Typical flow:
  1. Hive fetches credential state from Aden when needed
  2. Hive caches tokens locally for performance and resilience
  3. Refresh operations are delegated to Aden
  4. Optional usage reporting is sent back to Aden

​
API Contract

Aden credential sync expects these endpoint patterns:
  • GET /v1/credentials/{integration_id}
  • POST /v1/credentials/{integration_id}/refresh
  • GET /v1/credentials
  • GET /v1/credentials/{integration_id}/validate
  • POST /v1/credentials/{integration_id}/usage (optional)
  • GET /health
Authentication headers:
  • Authorization: Bearer {agent_api_key}
  • X-Tenant-ID: {tenant_id} (optional)

​
Local Integration Components

Implementation in Hive lives under:
  • core/framework/credentials/aden/client.py
  • core/framework/credentials/aden/provider.py
  • core/framework/credentials/aden/storage.py
These components provide:
  • HTTP client for Aden credential endpoints
  • CredentialProvider implementation for refresh/validate
  • Optional local cache + Aden fallback storage

​
Integration Patterns

Use encrypted local storage plus AdenSyncProvider for refresh and validation.

​
Cached Storage

Use AdenCachedStorage when intermittent connectivity is expected.

​
Multi-tenant

Create per-tenant provider/client instances with explicit tenant context and segregated credential paths.

​
Error Handling

Design for these cases:
  • Aden unavailable: use non-expired local token if present
  • Re-authorization required: surface reauth URL and fail explicitly
  • Rate-limited refresh: backoff based on retry hints

​
Security Checklist

  • Keep API keys out of source control
  • Use encrypted local storage for cached tokens
  • Scope credentials per tenant and environment
  • Log metadata, not token secrets