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

# Authentication

> How to authenticate with the CostHawk API and MCP server

## Before You Start

<Warning>
  CostHawk has two different credential types, and both can look like `ch_sk_...`.
  They are not interchangeable.
</Warning>

| If you are doing this                                       | Use this credential   | Where it goes                                                                  |
| ----------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------ |
| MCP, OTel ingest, or CostHawk API auth                      | CostHawk access token | `COSTHAWK_API_KEY` or `Authorization: Bearer ...` to CostHawk routes           |
| OpenAI / Anthropic / Google model requests through CostHawk | Wrapped key           | Provider SDK `api_key` or `Authorization` header, plus CostHawk proxy base URL |

<Info>
  If you are trying to send a wrapped key directly to Anthropic, OpenAI, or Google, stop and switch to the CostHawk proxy first. See <a href="/integrations/wrapped-keys">Wrapped Keys</a>.
</Info>

## Access Tokens

CostHawk uses access tokens to authenticate requests to the API and MCP server. Tokens are scoped to your account and can be created and revoked from your dashboard.

For MCP users, the recommended path is browser login:

```bash theme={null}
npm exec --yes costhawk@latest -- --login
```

That flow creates a token and configures MCP automatically.

### Creating a Token

1. Go to your [CostHawk dashboard](https://costhawk.ai/dashboard)
2. Start at **Access Setup** or go directly to **Settings → Access Tokens**
3. Click **Create Token**
4. Give your token a descriptive name (e.g., "Claude Code - Work Laptop")
5. Copy the token immediately - you won't be able to see it again

<Info>
  Access tokens may be prefixed with `ch_sk_`, but so are wrapped keys. The prefix alone does not tell you which endpoint to use.
</Info>

### Token Security

<Warning>
  **Never share your access tokens or commit them to version control.**
</Warning>

Best practices:

* Use environment variables to store tokens
* Create separate tokens for different environments (dev, staging, prod)
* Rotate tokens periodically
* Revoke tokens you no longer need

### Revoking a Token

If a token is compromised or no longer needed:

1. Go to **Access Setup** or **Settings → Access Tokens** in your dashboard
2. Find the token in the list
3. Click the trash icon to revoke it

Revoked tokens are immediately invalidated and cannot be used for future requests.

## Using Tokens

### MCP Server

Set the `COSTHAWK_API_KEY` environment variable in your MCP configuration:

```json theme={null}
{
  "mcpServers": {
    "costhawk": {
      "command": "npx",
      "args": ["--yes", "costhawk@latest"],
      "env": {
        "COSTHAWK_API_KEY": "YOUR_COSTHAWK_ACCESS_TOKEN"
      }
    }
  }
}
```

### API Requests

Include the token in the `Authorization` header:

```bash theme={null}
curl -X GET "https://costhawk.ai/api/usage/summary" \
  -H "Authorization: Bearer YOUR_COSTHAWK_ACCESS_TOKEN"
```

## Error Responses

| Status Code | Meaning                                 |
| ----------- | --------------------------------------- |
| `401`       | Missing or invalid token                |
| `403`       | Token doesn't have required permissions |
| `429`       | Rate limit exceeded                     |

<Tip>
  If you see authentication errors, verify your token is active in the dashboard under **Settings → Access Tokens**.
</Tip>

## Wrapped Keys Are Different

Wrapped keys are not covered by the auth flow above.

* Access tokens authenticate you to CostHawk
* Wrapped keys authenticate provider traffic to the CostHawk proxy

If you need OpenAI, Anthropic, or Google proxy setup, go to <a href="/integrations/wrapped-keys">Wrapped Keys</a>.