Skip to main content
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:
PrefixEnvironmentBehavior
hk_test_...TestSimulates sends without hitting AWS SES. No real delivery.
hk_live_...ProductionSends 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.
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.

​
Create a key

1

Open API Keys

Go to Settings > Email > API Keys and click Create.
2

Configure the key

Set the name, environment (test or live), scopes, rate limits, and any allowlists.
3

Copy the secret

Copy the full key value and store it in your secret manager.
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.

​
Permission scopes

Keys are least-privilege by default — assign only the scopes each key actually needs.
ScopeGrants
email:sendSend single emails via the SDK, REST API, or SMTP
email:batchSend batch emails (up to 100 per request)
email:domainsRead, add, and verify domains
email:templatesRead, create, update, and delete templates
email:webhooksRead, 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: 
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: 
import { Hiveku } from "@hiveku-apps/email";

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