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

# Wrapped Keys

> How to use CostHawk wrapped keys correctly with the proxy

Wrapped keys are for **provider SDK traffic through the CostHawk proxy**.

If you only remember one thing, remember this:

<Warning>
  A wrapped key must be used with a CostHawk proxy URL like `https://costhawk.ai/api/proxy/anthropic`.
  It will fail if you send it directly to `api.anthropic.com`, `api.openai.com`, or Google's direct endpoint.
</Warning>

## The Easy Rule

* If you are configuring **MCP**, **OTel**, or the **CostHawk API**, use a CostHawk access token with `COSTHAWK_API_KEY`.
* If you are configuring an **OpenAI, Anthropic, or Google SDK/client**, use a wrapped key and change the base URL to the CostHawk proxy.

## Two Different CostHawk Credentials

Both credentials may look like `ch_sk_...`. Do **not** identify them by prefix alone.

| Credential            | Created In                                                    | Used For                                                          | Send It To                                                                                                     | Do Not Send It To                                          |
| --------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| CostHawk access token | Browser login or Dashboard → Access Setup → MCP + OTel Tokens | MCP, OTel ingest, CostHawk API auth                               | `COSTHAWK_API_KEY` or `Authorization: Bearer ...` to CostHawk API routes                                       | Provider SDKs and direct OpenAI/Anthropic/Google endpoints |
| Wrapped key           | Dashboard → Access Setup → Wrapped Proxy Keys                 | OpenAI / Anthropic / Google model requests through CostHawk proxy | `Authorization: Bearer ch_sk_...` or provider SDK `api_key` against `https://costhawk.ai/api/proxy/{provider}` | Direct provider endpoints                                  |

## How To Use A Wrapped Key

<Steps>
  <Step title="Create a wrapped key">
    Go to <a href="https://costhawk.ai/dashboard/access">Access Setup</a>, then open <a href="https://costhawk.ai/dashboard/wrapped-keys">Wrapped Proxy Keys</a>. When prompted, paste your real provider inference key. CostHawk stores that real key behind the wrapped key.
  </Step>

  <Step title="Keep provider and proxy aligned">
    An Anthropic wrapped key must use the Anthropic proxy. An OpenAI wrapped key must use the OpenAI proxy.
  </Step>

  <Step title="Change your SDK base URL">
    Replace the provider's base URL with `https://costhawk.ai/api/proxy/{provider}`.
  </Step>

  <Step title="Use the wrapped key as the API key">
    Keep the wrapped key in the auth header or SDK `api_key` field. CostHawk resolves it to your real provider key server-side.
  </Step>
</Steps>

<Note>
  Wrapped keys sit in front of real inference-capable provider keys. Admin or read-only provider keys belong in <a href="/integrations/admin-api">Admin API Sync</a>, not in proxy traffic.
</Note>

## Wrong vs Right

### Wrong

This will fail, because the wrapped key is being sent directly to the provider:

```python theme={null}
from anthropic import Anthropic

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

### Right

This works, because the base URL points to the CostHawk proxy:

```python theme={null}
from anthropic import Anthropic

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

## Proxy Endpoints

| Provider      | Base URL                                  | Typical Auth                                                     |
| ------------- | ----------------------------------------- | ---------------------------------------------------------------- |
| OpenAI        | `https://costhawk.ai/api/proxy/openai`    | `Authorization: Bearer ch_sk_...`                                |
| Anthropic     | `https://costhawk.ai/api/proxy/anthropic` | `Authorization: Bearer ch_sk_...`                                |
| Google Gemini | `https://costhawk.ai/api/proxy/google`    | `Authorization: Bearer ch_sk_...` or `x-goog-api-key: ch_sk_...` |

## Provider-Specific Setup

<CardGroup cols={3}>
  <Card title="OpenAI Proxy" icon="bolt" href="/integrations/openai">
    OpenAI SDK examples and endpoint details
  </Card>

  <Card title="Anthropic Proxy" icon="message" href="/integrations/anthropic">
    Anthropic SDK examples and endpoint details
  </Card>

  <Card title="Google Gemini Proxy" icon="google" href="/integrations/google">
    Google Gemini proxy setup and request format
  </Card>
</CardGroup>

## When Not To Use Wrapped Keys

* If you want fast org-level visibility with no app code changes, start with <a href="/integrations/admin-api">Admin API Sync</a>.
* If you want Claude Code / Codex analytics and assistant-native tools, use <a href="/mcp-server/overview">MCP</a>.
* If you need CostHawk API auth, see <a href="/authentication">Authentication</a>.

## Related Concepts

Wrapped keys make more sense when you understand the architecture around them:

<CardGroup cols={3}>
  <Card title="LLM Gateway" icon="shuffle" href="/glossary/llm-gateway">
    Why centralized routing layers exist and what controls they add.
  </Card>

  <Card title="Serverless Inference" icon="rocket" href="/glossary/serverless-inference">
    The default runtime model you are buying when requests flow through provider APIs.
  </Card>

  <Card title="Max Tokens" icon="wrench" href="/glossary/max-tokens">
    The request-level output cap most teams enforce once traffic is routed through a proxy.
  </Card>
</CardGroup>