---
title: "Generate Key"
method: POST
path: "/api/keys/generate"
tags: ["api-keys"]
---

# Generate Key

`POST /api/keys/generate`

## Request

- Base URL: `https://api.halalterminal.com`
- URL: `https://api.halalterminal.com/api/keys/generate`
- Auth: none required

Generate a free-trial API key.

Creates a new API key with 500 free tokens for the given email
address. Generating again for the same email deactivates the prior
free key and carries its usage forward — it never resets the quota.

**curl example**:
```bash
curl -X POST https://api.halalterminal.com/api/keys/generate \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com"}'
```

**Python example**:
```python
import requests

resp = requests.post(
    "https://api.halalterminal.com/api/keys/generate",
    json={"email": "dev@example.com"},
)
key_data = resp.json()
print("Your API key:", key_data["api_key"])
```

## Request body

- GenerateKeyRequest: Request body for generating a new free-trial API key.
  - `email` string, email, required: Email address to associate with the new API key
  - `marketing_opt_in` boolean: Opt in to occasional product updates and onboarding tips. Defaults to False; transactional emails (key delivery, payment receipts, quota alerts) are always sent regardless.

## Response `200`

The newly generated API key with plan details

- GenerateKeyResponse: Response returned after successfully generating an API key.
  - `api_key` string, required: The generated API key
  - `email` string, required: Email address associated with the key
  - `plan` string, required: Plan tier assigned to this key (e.g. free)
  - `tokens_limit` integer, required: Monthly token allowance
  - `tokens_used` integer, required: Tokens consumed so far this period
  - `requests_limit` integer, required: Maximum number of requests allowed
  - `requests_used` integer, required: Number of requests consumed so far
  - `billing_period_end` string, nullable: ISO-8601 timestamp when the current billing period ends
  - `created_at` string, required: ISO-8601 timestamp when the key was created

## Other responses

- `422`: Validation Error
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/halalterminal/apis/halal-terminal-api.md) · [All operations](https://skmtc.dev/halalterminal/apis/halal-terminal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/halalterminal/apis/halal-terminal-api/revisions/78768b250943?raw)