API keys & authentication

Kinds of key

No API key can manage billing, members or other keys, or move money out: withdrawals, refunds and payout setup need the workspace owner signed in to the dashboard.

Which key to give what

Where a project key works

A project key passes every route that names its project: /api/projects/<id>/…, and item routes whose resource belongs to it — /api/databases/:id, /api/storage/:id, /api/functions/:id, /api/vectors/:id, /api/memory/:id, /api/agents/:id, /api/payments/:accountId, /api/auth-pools/:id, /api/deployments/:id.

It also sends mail (POST /api/mail/send) and calls the AI Gateway (/api/ai/chat, /api/ai/playground, /api/ai/v1/chat/completions and /api/ai/embeddings) for its own project. Leave projectId out (for AI, also the X-Harakumo-Project header) and the call acts for the key's project; naming another project is refused. The email quota and the AI spend are the workspace's, as with any key, and a read-only key can neither send mail nor spend on AI.

It is refused, with 403 "This API key only works on project N", on workspace-wide routes: listing projects, the rest of /api/mail/* (messages, settings, suppressions and sending domains), /api/ai/requests, /api/domains/*, /api/repos/*, /api/usage and billing.

Its mail goes out only as its own project. It sends from an address on the project's own sending domain (the domain of the project's saved From address) or from the shared no-reply; another domain of the workspace answers 403 from_not_project_domain. It never sends under another project's name or sender name, or a close variant of one (a name that contains one of five letters or more, or is one letter off one of six or more): 403 sender_name_other_project. A variant of a name its own project's name already contains is its own ("Fruitly API" may send as "Fruitly Receipts"), but another project's exact name never is. The same rules apply when it changes its project's mailFrom or mailSenderName with PATCH /api/projects/:id. To move a project to a new sending domain, a person sets its From address on the Mail page.

Create a key with the API

curl -X POST https://harakumo.com/api/orgs/<workspaceId>/api-keys \
  -H "Authorization: Bearer $HARAKUMO_API_KEY" -H "content-type: application/json" \
  -d '{ "name": "notes-app production", "access": "full", "projectId": 12 }'
# 201 → { "key": { "id", "prefix", "access", "project_id" }, "secret": "hk_live_…" }   (secret shown once)

Creating keys needs the admin role, so an API key (developer or viewer) cannot mint more keys. Use the dashboard, or an admin's connector.

Expiry and pause

• Give a key an end date: PUT /api/orgs/:id/api-keys/:keyId/expiry { days } (1 to 730, counted from now) or { expiresAt } (a date within 730 days); null, or DELETE on the same path, means it never expires. Past the date every request with it is refused with 401 key_expired. An expired key given a new date works again.
• Pause a key that may have leaked but that an app you cannot update yet still holds: POST /api/orgs/:id/api-keys/:keyId/pause. Every request with it is refused with 403 key_paused until DELETE on the same path resumes it. Nothing else about the key changes.
• Both need an owner or admin, answer the key with its state (active, expired, paused or revoked), and are written in the workspace's audit log. The same controls are in Settings → API access and in an admin's AI connector (set_api_key_expiry, pause_api_key).
• A key made by a person whose account Harakumo has suspended is refused too (403 key_creator_suspended) until the account is restored. Create a new key for the app.

Other credentials

Choosing a workspace

A key belongs to one workspace. A session or an all-workspaces connector acts in the workspace named by ?org=<id> or the x-harakumo-org header, else the one last chosen in the dashboard.

When a key is refused

Reference

import Harakumo from '@harakumo/sdk';
const hk = new Harakumo({ apiKey: process.env.HARAKUMO_API_KEY });   // baseUrl defaults to https://harakumo.com
// Errors throw HarakumoError with .status and .body (the JSON the API sent).

harakumo login --key hk_live_…     # or set HARAKUMO_API_KEY; --key and --url work on every command
harakumo whoami

Authorization: Bearer hk_live_…
GET    /api/orgs/:id/api-keys                 # list (admin+); secrets are never returned
POST   /api/orgs/:id/api-keys                 { "name", "access": "full" | "read", "projectId"? }
PUT    /api/orgs/:id/api-keys/:keyId/expiry   { "days": 90 } | { "expiresAt": "2027-01-31" } | { "days": null }
DELETE /api/orgs/:id/api-keys/:keyId/expiry   # never expires
POST   /api/orgs/:id/api-keys/:keyId/pause    # 403 key_paused until DELETE resumes it
DELETE /api/orgs/:id/api-keys/:keyId          # revoke