> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adenhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Aden Credential Sync

> Sync local Hive credentials with Aden-managed integrations

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

### Provider-only (recommended)

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

## Related

* [Credential Store](/building/credential-store)
* [Quickstart](/getting-started/quickstart)