Skip to main content
/v1/keys is excluded from the standard /v1/* authentication (ApiKeyAuthMiddleware): it has its own logic, described here. See also Security for the full model.

​
Access rules (V1, deliberately simple)

All key management requires Authorization: Bearer <HAKI_ADMIN_KEY>. The admin freely chooses org_id/project_id at creation and sees every key in the listing.

​
Creating a key

​
string
required
1 to 128 characters.
​
string
required
1 to 128 characters.
​
string
Max 128 characters.

​
Response — 201 Created

​
string
required
The clear key (hk_...) — returned only once, here. Only its sha256 hash is stored afterwards; it can never be retrieved again.
​
uuid
required
​
string
required
The first 8 characters, for masked listings.
​
string
required
​
string
required
​
string | null
​
datetime
required

​
Listing keys (masked)

Without HAKI_ADMIN_KEY, the listing is scoped to the calling key’s project.
​
KeyOut[]
required
Never the key nor its hash — only prefix.

​
Revoking a key

Sets revoked_at — immediate effect: the key returns 401 unauthorized on the very next call.
​
uuid
required
​
string
default:"revoked"

​
Possible errors

unauthorized (401), forbidden_scope (403 — a key tries to create a key for an org_id/project_id other than its own), key_not_found (404).

​
Organization provisioning (console-only)

Internal endpoint, called only by the console’s Next.js backend with an already-verified Clerk identity — never by a browser, never by a customer’s hk_ key. Authenticated by a single shared secret (HAKI_CONSOLE_SERVICE_KEY), not the standard key model. Not covered by the SDK.
Takes {owner_ref, name}; generates a server-side org_id (never supplied by the caller, unlike the /v1/keys bootstrap), creates a prj_<org_id>_default project and a key. A repeat call for an already known owner_ref does not recreate the organization: it mints a new key on the same project instead (org_created: false).