API Keys

Manage API keys for programmatic access to the KeeperHub API.

Key Types

KeeperHub has two distinct key systems, managed at different endpoints. They are not interchangeable.

For typical programmatic API access use organization (kh_) keys.

Organization Keys (kh_)

Issued per-organization. Create them from Settings > API Keys > Organisation in the dashboard, or via the endpoints below.

List Organization Keys

GET /api/keys

Accepts session or API-key authentication. Returns a paginated list of non-revoked keys for the active organization. Use the page (1-based) and limit query parameters to page through results.

Response

{
  "items": [
    {
      "id": "key_123",
      "name": "Production Key",
      "keyPrefix": "kh_a1B2c",
      "createdAt": "2024-01-01T00:00:00Z",
      "lastUsedAt": "2024-01-15T12:00:00Z",
      "expiresAt": null,
      "scope": "mcp:read mcp:write",
      "createdByName": "Jane Doe",
      "createdByEmail": "[email protected]",
      "createdByRole": "admin"
    }
  ],
  "meta": { "total": 1, "page": 1, "pageSize": 50, "totalPages": 1 },
  "_links": {
    "self": "/api/keys?page=1&limit=50",
    "first": "/api/keys?page=1&limit=50",
    "prev": null,
    "next": null,
    "last": "/api/keys?page=1&limit=50"
  }
}

keyPrefix is the first 8 characters of the key (kh_ plus 5 more), kept for identification. The full key is never returned after creation.

Create Organization Key

POST /api/keys

Session authentication required. Cannot be invoked with an API key. Otherwise a leaked key could mint additional keys for the same organization.

Request Body

{
  "name": "My API Key",
  "expiresAt": "2025-01-01T00:00:00Z"
}

expiresAt is optional. Omit for a non-expiring key.

Response

{
  "id": "key_123",
  "name": "My API Key",
  "key": "kh_full_api_key_here",
  "keyPrefix": "kh_full_",
  "createdAt": "2024-01-01T00:00:00Z",
  "expiresAt": null
}

Copy the key value immediately. It is only shown once.

Revoke Organization Key

DELETE /api/keys/{keyId}

Soft-revokes the key. Subsequent requests with that key return 401.

Response

{
  "success": true
}

User Keys (wfb_)

Issued per-user. Intended for webhook triggers, not for general REST API access.

List User Keys

GET /api/api-keys

Session authentication required.

Create User Key

POST /api/api-keys

Session authentication required.

Request Body

{
  "name": "My Webhook Key"
}

Delete User Key

DELETE /api/api-keys/{keyId}

Session authentication required. Revokes the key. This action cannot be undone.

Security Notes

• Keys are hashed with SHA256 before storage; only the prefix is kept for identification.
• Anonymous users cannot create API keys.
• Revoke compromised keys immediately.
• Store keys in environment variables, not in source code.
• Key creation and personal-key deletion require session authentication, so a leaked API key cannot mint or delete other keys.