# Authentication and keys

Anonymous reads, emailed Free keys and entitled research credentials.

## Public data
Anonymous GET requests work on datasets and series. With a key, send Authorization: Bearer followed by the key. Never put a key in a URL, committed config or a public conversation.

```curl
curl --fail-with-body --silent --show-error --max-time 30 -H "Authorization: Bearer $CS_API_KEY" "https://china-snapshot.com/api/series/pmi-manufacturing"
```

```python
import json
import os
from urllib.request import Request, urlopen
request = Request('https://china-snapshot.com/api/series/pmi-manufacturing', headers={'Authorization': 'Bearer ' + os.environ['CS_API_KEY']})
with urlopen(request, timeout=30) as response:
    data = json.load(response)
print(json.dumps(data, ensure_ascii=False))
```

```typescript
const key = process.env.CS_API_KEY;
if (!key) throw new Error("Set CS_API_KEY first");
const response = await fetch("https://china-snapshot.com/api/series/pmi-manufacturing", { headers: { Authorization: `Bearer ${key}` } });
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
```

## Request a key
Use the [signup form](/api#get-a-key) or the requestApiKey operation in the [API reference](/docs/api/request-api-key). Supply email in JSON and Accept: application/json. The response carries status, limits, documentation links and next_steps.

| Result | What to do |
| --- | --- |
| key_emailed | Retrieve the key from your authorized inbox and store it securely |
| key_shown_once | Store the response key immediately; this Free fallback is not account-linked or upgradeable |
| key_exists | Find the original email or request replacement from the same address |
| unavailable / email_failed | No usable key was issued; follow the error and retry later |

## Replace or revoke
For an emailed Free key, contact [contact@china-snapshot.com](mailto:contact@china-snapshot.com) from the same address. Support revokes the old key so a replacement can be requested. Subscriber key management is available through the authenticated account workflow; a Free emailed key is not a session credential for that workflow. Do not invent a self-service Free-key rotation endpoint.

## Research access
MCP tools and research invocations require an API key (free or Pro) in addition to the public protocol methods. A rejected credential returns an authentication error; a valid but unentitled credential cannot unlock a tool. See [MCP](/docs/mcp/overview).