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

# API Keys

> Create, manage, and secure API keys for email sending

API keys authenticate every request to the Hiveku Email API. Each key has its own scopes, rate limits, and optional allowlists so you can tightly control what a key can do.

## Test vs live keys

Hiveku issues two flavors of keys, distinguished by prefix:

| Prefix        | Environment | Behavior                                                    |
| ------------- | ----------- | ----------------------------------------------------------- |
| `hk_test_...` | Test        | Simulates sends without hitting AWS SES. No real delivery.  |
| `hk_live_...` | Production  | Sends real email through AWS SES. Counts against your plan. |

Test keys are ideal for CI/CD, local development, and PR preview environments — you get full API responses (including a `messageId`) without risking a real send or burning quota.

<Tip>
  Wire your app so the key is pulled from an environment variable (`HIVEKU_API_KEY`). Point dev/staging at an `hk_test_` key and production at an `hk_live_` key.
</Tip>

## Create a key

<Steps>
  <Step title="Open API Keys">
    Go to **Settings > Email > API Keys** and click **Create**.
  </Step>

  <Step title="Configure the key">
    Set the name, environment (test or live), scopes, rate limits, and any allowlists.
  </Step>

  <Step title="Copy the secret">
    Copy the full key value and store it in your secret manager.
  </Step>
</Steps>

<Warning>
  The secret is shown **only once** at creation. Hiveku stores only a hash — we cannot recover the value afterward. If you lose the key, revoke it and create a new one.
</Warning>

## Permission scopes

Keys are least-privilege by default — assign only the scopes each key actually needs.

| Scope             | Grants                                            |
| ----------------- | ------------------------------------------------- |
| `email:send`      | Send single emails via the SDK, REST API, or SMTP |
| `email:batch`     | Send batch emails (up to 100 per request)         |
| `email:domains`   | Read, add, and verify domains                     |
| `email:templates` | Read, create, update, and delete templates        |
| `email:webhooks`  | Read, create, and update webhook endpoints        |

Most application keys only need `email:send` (and optionally `email:batch`). Admin-style keys used by internal tools or deployment scripts may need the management scopes.

## Rate limiting

Each key has configurable rate limits:

* **Per second** — Default **10 emails/second**. Burst-friendly for transactional traffic.
* **Per day** — Optional daily cap to prevent runaway loops or abuse.

Rate-limited responses return `429 Too Many Requests` with a `Retry-After` header. The SDK automatically retries with exponential backoff.

## Domain allowlist

Restrict a key to send only from a specific set of verified domains. Useful for multi-tenant setups where each tenant gets its own key scoped to its own domain.

## IP allowlist

Optionally restrict a key to a set of source IPs or CIDR ranges (e.g., your production NAT gateway). Any request from outside the allowlist returns `403 Forbidden`.

## Usage tracking

For every key, Hiveku tracks:

* Last-used timestamp
* Total sends (lifetime and 30-day)
* Rate-limit hits
* Failed auth attempts

Review this on the API Keys page to spot unused keys you can retire.

## Revoking keys

Click **Revoke** on any key to invalidate it immediately. Revocation is instant — in-flight requests using the key will start failing with `401 Unauthorized`.

## Authentication

All REST API requests must include the key as a Bearer token:

```bash theme={null}
curl https://api.hiveku.com/v1/email/send \
  -H "Authorization: Bearer hk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@mail.acme.com",
    "to": "customer@example.com",
    "subject": "Hello",
    "html": "<p>Hi!</p>"
  }'
```

The SDK handles this header for you — just pass the key when constructing the client:

```ts theme={null}
import { Hiveku } from "@hiveku-apps/email";

const hiveku = new Hiveku({ apiKey: process.env.HIVEKU_API_KEY! });
```