---
title: Authentication
description: How to authenticate requests - pass your API key as an api_key query parameter. Keys have prefixes, can be rotated, and are tied to a workspace.
order: 5
---

# Authentication

Every request to `https://api.chocodata.com` must include your API key as an `api_key` query parameter:

```http
GET /api/v1/walmart/product?api_key=cd_live_YOUR_KEY_HERE&query=5085206428
```

```bash
curl "https://api.chocodata.com/api/v1/walmart/product?api_key=cd_live_YOUR_KEY_HERE&query=5085206428"
```

Requests without a valid key return `401 Unauthorized`. Unauthorized requests are free - they never touch your credit balance.

## Key format

All keys start with a prefix so you can tell them apart at a glance:

| Prefix | Meaning |
|---|---|
| `cd_live_` | Production traffic. This is what you want 99% of the time. |
| `cd_test_` | Sandbox keys (roadmap). Return deterministic fixtures, never hit a live target, never bill. |

The 12 characters after the prefix (e.g. `cd_live_Tq0x4k9Pd8Mn`) form the shortprefix displayed in the dashboard and in our logs - enough to identify a key without revealing the full secret.

## Where to get a key

Sign up at [app.chocodata.com](https://app.chocodata.com) (Google sign-in or email + password; no card required for the free tier). Go to **Settings > API keys** and click **Generate new key**. The full key is shown exactly once at creation time - save it to your secrets manager right then.

## Rotating keys

1. Generate a second key in the dashboard.
2. Deploy the new key to your app.
3. Revoke the old key.

Revocation takes effect within ~30 seconds globally. Revoked keys return `401 Unauthorized` with `{"error":"revoked"}`.

## Multiple keys, workspace-wide

You can have up to 20 active keys per workspace. Usage is aggregated across all of them - your plan's monthly credit allowance is per workspace, not per key. The **Usage** tab lets you filter by key so you can tell which service burned through what.

## Key hygiene (important)

- **Never embed a key in client-side code** - browsers, mobile apps, public repos are all one-way streets. Proxy requests through your own server.
- **Store keys in a secrets manager.** Not in `.env` files checked into git. Not in Slack screenshots.
- **Use a separate key per environment** (`cd_live_...` for prod, another for staging). When a key leaks, you revoke only the affected environment.
- **Rotate on a schedule** - quarterly is a reasonable cadence. If a key ever appears in logs, git history, or a paste bin, rotate immediately.

## IP allow-lists (roadmap)

Restricting a key to a list of egress IPs will be available on Pro and Custom plans. Write to <hello@chocodata.com> if you need it sooner - we can enable it manually.

## What happens to usage when a key is revoked

Historical usage for a revoked key stays in your dashboard for 90 days under **Usage**. The key itself can no longer authenticate, so no new charges are possible against it.

## Related

- [Getting started](/docs/getting-started) - make your first request
- [Core concepts](/docs/core-concepts) - how the API works
- [Error codes](/docs/guides/errors) - full list of `401` reasons
- [Rate limits & concurrency](/docs/guides/rate-limits) - per-key ceilings