Skip to main content

​
Before You Start

CostHawk has two different credential types, and both can look like ch_sk_.... They are not interchangeable.
If you are doing thisUse this credentialWhere it goes
MCP, OTel ingest, or CostHawk API authCostHawk access tokenCOSTHAWK_API_KEY or Authorization: Bearer ... to CostHawk routes
OpenAI / Anthropic / Google model requests through CostHawkWrapped keyProvider SDK api_key or Authorization header, plus CostHawk proxy base URL
If you are trying to send a wrapped key directly to Anthropic, OpenAI, or Google, stop and switch to the CostHawk proxy first. See Wrapped Keys.

​
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: 
npm exec --yes costhawk@latest -- --login
That flow creates a token and configures MCP automatically.

​
Creating a Token

  1. Go to your CostHawk 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
Access tokens may be prefixed with ch_sk_, but so are wrapped keys. The prefix alone does not tell you which endpoint to use.

​
Token Security

Never share your access tokens or commit them to version control.
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: 
{
  "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: 
curl -X GET "https://costhawk.ai/api/usage/summary" \
  -H "Authorization: Bearer YOUR_COSTHAWK_ACCESS_TOKEN"

​
Error Responses

Status CodeMeaning
401Missing or invalid token
403Token doesn’t have required permissions
429Rate limit exceeded
If you see authentication errors, verify your token is active in the dashboard under Settings → Access Tokens.

​
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 Wrapped Keys.