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

# Authentication

> Authenticate your requests to the Hey Chocolate API using API keys.

All requests to the Hey Chocolate API require authentication via an API key passed in the `X-API-Key` header.

## Obtaining an API key

1. Log in to the [Hey Chocolate Dashboard](https://dashboard.heychocolate.com)
2. Navigate to **Settings > API Keys**
3. Click **Create API Key** and give it a descriptive name
4. Copy the key immediately — it will only be shown once

<Warning>
  Store your API key securely. Never commit it to version control or expose it in client-side code.
</Warning>

## Using your API key

Include the `X-API-Key` header in every request:

```bash theme={null}
curl -X POST https://api.heychocolate.com/graphql \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_abc123def456" \
  -d '{"query": "{ me { id name tier } }"}'
```

## Environments

| Environment    | Base URL                                   | Purpose                                |
| -------------- | ------------------------------------------ | -------------------------------------- |
| **Production** | `https://api.heychocolate.com/graphql`     | Live data and production workloads     |
| **Sandbox**    | `https://sandbox.heychocolate.com/graphql` | Testing and development with mock data |

Sandbox API keys start with `sk_sandbox_`, production keys with `sk_live_`.

## API key tiers

Your API key is associated with a tier that determines rate limits and available features:

| Tier           | Requests/min | Features                                                        |
| -------------- | ------------ | --------------------------------------------------------------- |
| **Free**       | 60           | Core queries, basic calculations                                |
| **Growth**     | 600          | All calculations, scenarios, equivalencies                      |
| **Enterprise** | 6,000+       | Full access including DPP generation, asset rendering, webhooks |

<Info>
  Contact [sales@heychocolate.com](mailto:sales@heychocolate.com) to upgrade your tier or request custom limits.
</Info>

## Key rotation

You can rotate API keys from the Dashboard without downtime:

1. Create a new key
2. Update your application to use the new key
3. Verify requests succeed with the new key
4. Revoke the old key

## Webhook authentication

When receiving webhooks from Hey Chocolate, verify the signature in the `X-HC-Signature` header using your webhook secret. See [Webhooks](/api-reference/webhooks) for details.