Managing API Keys

API keys are the credentials your application uses to authenticate with the Koji API. Each key is scoped to a specific project and carries permissions that control what operations it can perform. This article covers the full lifecycle of managing API keys -- from creation through rotation and revocation.

---

Where to Find API Key Management

API keys are managed from your profile:

1. Open the Koji dashboard.
2. Navigate to Dashboard > Profile > API Keys.
3. The API Keys section displays all keys across your projects.

You need project admin or owner permissions to manage API keys.

---

Creating an API Key

To create a new key:

1. Click Create API Key on the API Keys page.
2. Enter a name for the key. Use something descriptive that identifies where the key will be used (e.g., "Production Backend", "Staging Server", "CI/CD Pipeline").
3. Select permissions for the key:
   • interview:start -- Allows starting new interviews
   • interview:chat -- Allows sending and receiving messages during an interview
   • interview:complete -- Allows completing interviews and triggering analysis
   • interview:read -- Allows retrieving interview data, transcripts, and analysis
4. Click Generate.
5. Copy the key immediately. Koji displays the full key only once at creation time. After you close this dialog, only the key prefix is visible.

Store the key in a secure location such as an environment variable, a secrets manager, or an encrypted configuration file. Never hardcode API keys in your source code.

---

Permissions in Detail

Each permission controls access to specific API endpoints:

interview:start

Allows calling POST /api/v1/interviews/start. This is the minimum permission needed to begin an interview via the API. The response includes the interview ID, session token, and initial message.

interview:chat

Allows sending messages to an active interview session and receiving AI responses. This permission is required for any integration that manages the conversation flow programmatically.

interview:complete

Allows calling POST /api/v1/interviews/:id/complete. This marks an interview as finished and triggers the automatic analysis pipeline.

interview:read

Allows calling GET /api/v1/interviews/:id. This lets you retrieve the full transcript, analysis results, quality scores, and statistics for any interview in the project.

Combining Permissions

Most integrations need all four permissions. However, the principle of least privilege suggests you only grant what is needed:

• Full integration (start, chat, manage, retrieve): All four permissions.
• Read-only dashboard: Only interview:read.
• Interview launcher: interview:start and interview:complete (retrieval handled separately).
• Chat bot integration: interview:start, interview:chat, and interview:complete.

See API Authentication for more details on how permissions work with the API.

---

Viewing Existing Keys

The API Keys section lists all active keys:

The Last Used timestamp helps you identify inactive keys that may be candidates for revocation.

---

Updating Key Settings

You can update key settings without generating a new key:

1. Find the key in the list.
2. Click the Edit button.
3. Update the name, active status, allowed origins, or rate limit as needed.
4. Click Save.

Changes take effect immediately. Any in-flight requests using the old settings may succeed if they were already authenticated, but subsequent requests use the updated configuration.

---

Revoking a Key

If a key is compromised, no longer needed, or being rotated out:

1. Find the key in the list.
2. Click the Revoke button.
3. Confirm the action in the dialog.

Revocation is immediate and permanent. Any request using the revoked key fails immediately with a 401 Unauthorized response. There is no way to un-revoke a key -- you must create a new one.

---

Key Rotation Best Practices

Regular key rotation limits the damage if a key is ever exposed. Here is the recommended rotation process:

1. Create a new key with the same permissions as the one you are replacing.
2. Update your application to use the new key.
3. Verify the new key works by monitoring API responses.
4. Revoke the old key once you confirm the new key is active in all environments.

Do not revoke the old key before confirming the new one works. Having two active keys simultaneously during rotation is expected and safe.

A quarterly rotation schedule (every 90 days) is a good starting point for most teams.

---

How Many Keys Should You Have

There is no strict limit on the number of API keys per project, but here are some guidelines:

• One key per environment. Separate keys for development, staging, and production make it easy to revoke a key in one environment without affecting others.
• One key per service. If multiple backend services call the Koji API, each should have its own key for easier auditing and independent revocation.
• Avoid sharing keys. Never share a single key between multiple developers or services. Individual keys make access control and auditing possible.

---

API Key Format

Koji API keys follow the format pk_live_ followed by 32 characters. For example:

pk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345

When stored, only the first 12 characters (the prefix) are retained for identification. The full key is shown only once at creation time.

---

Rate Limiting

Each API key has a configurable rate limit (default: 60 requests per minute). When exceeded, subsequent requests receive a 429 Too Many Requests response. See Rate Limits and CORS for details on headers and retry strategies.

---

Security Best Practices

• Never commit keys to version control. Use environment variables or a secrets manager.
• Set allowed origins. Restrict which domains can use the key to prevent misuse if the key is exposed.
• Use the minimum permissions needed. Grant only the permissions each integration actually requires.
• Monitor the Last Used timestamp. Revoke keys that have not been used in 90+ days.
• Rotate keys quarterly. Regular rotation limits exposure from undetected leaks.
• Use HTTPS only. All API requests must use HTTPS. HTTP requests are rejected.

For more on API integration, see the API Authentication guide.