**Source:** https://heykiku.com/help/api-best-practices

# API best practices

Following these conventions keeps your integrations stable, your audit trail clean, and your blast radius small when a key leaks.

## Scope of least privilege

Default to `read` scope. Only mint a `read + write` key if your integration actually uploads documents, creates folders, or approves drafts.

A read-only integration that gets compromised can't damage your knowledge base. A write-scope key with a bad rotation policy is the one that wipes folders.

## Name keys descriptively

The key name is the only label you'll have when auditing usage in the dashboard. `"CI Document Sync — production"` beats `"key-1"` six months later.

```
✓  "Notion → heykiku sync (production)"
✓  "Google Drive ingest (staging)"
✗  "test"
✗  "my key"
```

## One key per integration

Don't share a single key across multiple integrations. If you need to revoke one to roll credentials, the others shouldn't break.

This also keeps your audit logs readable — the `apiKeyNameSnapshot` field on conversations records *which* key or OAuth client started the chat, and that signal disappears when one key serves three different systems.

## Always scope keys to a CIDR for production

A key with no CIDR allowlist works from any IP on the internet. For server-to-server integrations where you know the origin, set `allowedCidrs` to the runner's public IP range. For a single VPS, a /32 is fine.

Be careful with `0.0.0.0/0` — it's equivalent to no allowlist and the API rejects it at issuance to prevent accidental holes.

CI runners with rotating IPs are the tricky case. Most managed CI providers publish an egress IP list — check your CI's docs and paste those ranges into the key's allowlist.

## Rotate on a schedule, not on incident

If you wait for an incident to rotate keys, you'll roll under pressure and make mistakes. Pick a cadence — quarterly for production, monthly for high-risk integrations — and rotate.

The simplest rotation flow:

1. Create a new key with the same scope and CIDR as the old one
2. Deploy the new key to your integration
3. Verify it works for a day
4. Revoke the old key

`expiresAt` makes this enforced: a key that auto-expires forces the rotation to happen on a schedule whether you remember or not.

## Never commit keys

Use environment variables, secret managers, or your CI's encrypted-vars feature. `.env` files belong in `.gitignore` — heykiku keys in a public repo get auto-revoked, but that's the safety net, not the plan.

If you do leak a key:

1. Revoke it immediately (`DELETE /api/api-keys/{id}`)
2. Audit the conversations and documents touched while the leaked key was live
3. Issue a new key with tighter CIDR scoping

## Monitor `X-RateLimit-Remaining`

If your integration starts approaching the bucket ceiling, you'll see it in `X-RateLimit-Remaining` before it manifests as 429s. Catching this early lets you batch or back off without user-visible failures. See [rate limits and error codes](https://heykiku.com/help/api-rate-limits) for the full table.