API Key

What Is an API Key?

An API key is a unique secret string that identifies and authenticates a client application or user when making requests to an API. Instead of requiring a username and password on every call, the API key acts as a pre-shared credential that proves you are an authorized consumer of the service.

API keys are typically 32–64 characters long and look something like this:

knowledgesdk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

KnowledgeSDK uses the prefix knowledgesdk_live_ for all API keys, making them easy to identify and allowing you to scan your codebase for accidental exposure.

How API Keys Are Passed

There are two common delivery mechanisms:

• HTTP header — the most secure approach. KnowledgeSDK expects x-api-key: knowledgesdk_live_* on every authenticated request.
• Query parameter — convenient for quick tests but riskier because URLs are often logged: ?api_key=knowledgesdk_live_*.
• Bearer token — some services use Authorization: Bearer <key> instead of a custom header.

Always prefer the HTTP header approach in production code. Query parameters appear in server logs, browser history, and CDN access logs.

What API Keys Control

When you hit a KnowledgeSDK endpoint such as POST /v1/extract or POST /v1/search, the server:

1. Reads the x-api-key header.
2. Looks up the key in the api_keys table.
3. Validates that the key is active and belongs to a valid plan.
4. Tracks usage against your monthly quota.
5. Scopes all extracted knowledge to your isolated Typesense collection.

This means every API key represents a complete, isolated tenant. Data extracted under one key is never visible to another.

Best Practices

• Never commit API keys to source control. Use environment variables (KNOWLEDGE_API_KEY=knowledgesdk_live_...) and add .env to your .gitignore.
• Rotate keys regularly. If a key is compromised, generate a new one from the dashboard and revoke the old one immediately.
• Use separate keys per environment. Keep distinct keys for development, staging, and production so a test run cannot pollute production data.
• Set least-privilege scopes when available. Some APIs allow read-only keys; use them for integrations that only need to query, not write.
• Monitor usage anomalies. A sudden spike in GET /v1/account usage metrics can indicate an exposed key being abused.

API Keys vs. Other Auth Methods

For most backend integrations, an API key is the right starting point. When you need to act on behalf of specific end-users, OAuth 2.0 becomes more appropriate.