# CostHawk Docs

CostHawk supports four main integration paths:

1. Admin API Sync for provider-level reporting
2. MCP for assistant-native usage analysis and local workflows
3. OTel for telemetry ingestion
4. Wrapped-key proxy routing for provider SDK traffic that needs request-level attribution or policy controls

## Critical Credential Rule

CostHawk has two distinct credential types that may both look like `ch_sk_...`.
Do not determine usage by prefix.
Determine usage by endpoint and workflow.

### Access Token

- Purpose: MCP, OTel ingest, CostHawk API auth
- Where to use it:
  - `COSTHAWK_API_KEY`
  - `Authorization: Bearer ...` to CostHawk API routes
- Where not to use it:
  - direct provider SDK calls
  - OpenAI / Anthropic / Google model endpoints

Canonical docs:
- [Authentication](https://docs.costhawk.ai/authentication)
- [MCP Server Overview](https://docs.costhawk.ai/mcp-server/overview)

### Wrapped Key

- Purpose: provider model requests routed through the CostHawk proxy
- Where to use it:
  - OpenAI SDK with base URL `https://costhawk.ai/api/proxy/openai`
  - Anthropic SDK with base URL `https://costhawk.ai/api/proxy/anthropic`
  - Google SDK or HTTP client with base URL `https://costhawk.ai/api/proxy/google`
- Where not to use it:
  - `COSTHAWK_API_KEY`
  - direct `api.openai.com`
  - direct `api.anthropic.com`
  - direct Google native endpoint

Canonical docs:
- [Wrapped Keys](https://docs.costhawk.ai/integrations/wrapped-keys)
- [OpenAI](https://docs.costhawk.ai/integrations/openai)
- [Anthropic](https://docs.costhawk.ai/integrations/anthropic)
- [Google Gemini](https://docs.costhawk.ai/integrations/google)

## Quick Decision Matrix

### If the user says:

- "Set up MCP" or "connect Claude Code / Codex":
  - use a CostHawk access token
  - docs: [Quickstart](https://docs.costhawk.ai/quickstart), [Authentication](https://docs.costhawk.ai/authentication)

- "Set up OTel" or "telemetry ingest":
  - use a CostHawk access token
  - docs: [OTel](https://docs.costhawk.ai/integrations/otel)

- "Track OpenAI / Anthropic / Google requests through CostHawk":
  - use a wrapped key
  - change the SDK base URL to the CostHawk proxy
  - docs: [Wrapped Keys](https://docs.costhawk.ai/integrations/wrapped-keys)

- "Get usage fast with no code changes":
  - use Admin API Sync first
  - docs: [Admin API Sync](https://docs.costhawk.ai/integrations/admin-api)

## Wrong vs Right

### Wrong

Using a wrapped key directly against the provider:

```python
from anthropic import Anthropic

client = Anthropic(
    api_key="ch_sk_...",
    base_url="https://api.anthropic.com",
)
```

### Right

Using a wrapped key against the CostHawk proxy:

```python
from anthropic import Anthropic

client = Anthropic(
    api_key="ch_sk_...",
    base_url="https://costhawk.ai/api/proxy/anthropic",
)
```

## Common Failure Modes

- `401 invalid x-api-key` from Anthropic or OpenAI after using `ch_sk_...`
  - Cause: wrapped key was sent directly to the provider instead of the CostHawk proxy

- user asks whether `ch_sk_...` is an MCP token or a wrapped key
  - Answer: prefix is ambiguous in this product; determine by intended endpoint

- user points an agent at docs and asks "how do I use this key?"
  - Start with:
    - [Wrapped Keys](https://docs.costhawk.ai/integrations/wrapped-keys)
    - [Authentication](https://docs.costhawk.ai/authentication)
  - Then choose based on the endpoint they are trying to hit

## Best Docs To Read In Order

1. [Quickstart](https://docs.costhawk.ai/quickstart)
2. [Wrapped Keys](https://docs.costhawk.ai/integrations/wrapped-keys)
3. [Authentication](https://docs.costhawk.ai/authentication)
4. [Integration Overview](https://docs.costhawk.ai/integrations/overview)
5. Provider-specific integration page if proxy routing is needed