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 at the project level:

1. Open the project you want to integrate with.
2. Navigate to Settings > Integrations.
3. The API Keys section displays all keys for this project.

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 Integrations 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:read — Allows retrieving interview data, transcripts, and analysis
   • interview:complete — Allows completing interviews and triggering 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 last four characters are 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: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.

interview:complete

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

Combining Permissions

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

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

---

Viewing Existing Keys

The API Keys section on the Integrations page lists all active keys for the project:

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

---

Updating Key Permissions

You can change the permissions on an existing key without generating a new one:

1. Find the key in the list.
2. Click the Edit button (pencil icon).
3. Check or uncheck permissions as needed.
4. Click Save.

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

---

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 rotation.
• Fewer is simpler. Do not create keys "just in case." Each key is a credential that needs to be managed and secured.

---

Security Recommendations

• Store keys in environment variables or a secrets manager. Never in source code.
• Do not share keys across team members. Each developer can create their own key for local development.
• Monitor the Last Used timestamp. Keys that have not been used in months may be orphaned and should be revoked.
• Use server-side calls only. Never expose API keys in client-side JavaScript, mobile apps, or public repositories.
• Set up alerts. If your secrets manager supports it, set alerts for key access to detect potential misuse.

For a deeper dive into authentication, see API Authentication. For information about BYOK (AI provider keys, which are different from project API keys), see Bring Your Own Key.

---

Next Steps

• Understand the full authentication model
• Learn about BYOK for AI provider keys