API Keys Reference

CRUD operations for managing operator API keys.

Base path: /functions/v1/api-keys

Authentication: Authorization: Bearer oh_live_... or Supabase JWT (for listing and management)

---

Create a key {#create}

POST /api-keys

Creates a new API key for an operator. The plaintext key is returned once in the response — store it securely.

Request

Field	Type	Required	Description
operatorId	string	Yes	The operator ID to create the key for
label	string	No	A descriptive label (e.g. "Production backend")

Example

curl -X POST https://api.onehazel.com/api-keys \
  -H "Content-Type: application/json" \
  -d '{
    "operatorId": "op_abc123",
    "label": "Production backend"
  }'

Response (201)

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "key": "oh_live_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
    "label": "Production backend",
    "createdAt": "2026-04-06T12:00:00.000Z"
  }
}

Store your key

The key field is only returned in this response. It is stored as a SHA-256 hash and cannot be retrieved later. If you lose it, revoke the key and create a new one.

---

List keys {#list}

GET /api-keys

Lists all API keys for the authenticated operator. Keys are returned with hashed values — never in plaintext.

Supports both API key auth (oh_live_...) and JWT auth (Supabase session). When authenticated, results are filtered to show only the operator's own keys.

Example

curl https://api.onehazel.com/api-keys \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "operatorId": "op_abc123",
      "keyHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "label": "Production backend",
      "createdAt": "2026-04-06T12:00:00.000Z",
      "lastUsedAt": "2026-04-06T14:30:00.000Z",
      "revoked": false
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "operatorId": "op_abc123",
      "keyHash": "d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592",
      "label": "Staging ETL",
      "createdAt": "2026-03-15T09:00:00.000Z",
      "lastUsedAt": null,
      "revoked": false
    }
  ]
}

---

Rename a key {#rename}

PATCH /api-keys

Updates the label on an existing key.

Request

Field	Type	Required	Description
id	string	Yes	The key ID
label	string	Yes	The new label

Example

curl -X PATCH https://api.onehazel.com/api-keys \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "label": "Production v2"
  }'

Response

{
  "success": true,
  "message": "Key renamed"
}

---

Revoke a key {#revoke}

DELETE /api-keys?id=<keyId>

Soft-revokes an API key. The key remains in the database but can no longer be used for authentication.

Query parameters

Parameter	Type	Required	Description
id	string	Yes	The key ID to revoke

Example

curl -X DELETE "https://api.onehazel.com/api-keys?id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY"

Response

{
  "success": true,
  "message": "Key revoked"
}

Last-key guard

You cannot revoke your last active API key. If you try, the API returns:

{
  "success": false,
  "error": "Cannot revoke your last active API key — create a new one first"
}

HTTP status: 400

---

Hard delete a key {#hard-delete}

DELETE /api-keys?id=<keyId>&hard=true

Permanently removes a revoked key from the database.

Prerequisite: The key must already be revoked. Attempting to hard-delete an active key returns an error.

Example

curl -X DELETE "https://api.onehazel.com/api-keys?id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&hard=true" \
  -H "Authorization: Bearer oh_live_YOUR_API_KEY"

Response

{
  "success": true,
  "message": "Key deleted"
}

Error for active key

{
  "success": false,
  "error": "Cannot delete an active key — revoke it first"
}

---

Error codes

HTTP Status	Error	Description
400	operatorId is required	Missing operatorId on create
400	id and label are required	Missing fields on rename
400	Query parameter 'id' is required	Missing key ID on delete
400	Cannot revoke your last active API key	Last-key guard
400	Cannot delete an active key	Must revoke before hard delete
405	Method not allowed	Unsupported HTTP method
500	Failed to create key	Database error on create
500	Failed to list keys	Database error on list
500	Failed to rename key	Database error on rename
500	Failed to revoke key	Database error on revoke
500	Failed to delete key	Database error on delete