{"site":{"name":"Koji","description":"AI-native customer research platform that helps teams conduct, analyze, and synthesize customer interviews at scale.","url":"https://www.koji.so","contentTypes":["blog","documentation"],"lastUpdated":"2026-05-18T12:55:14.429Z"},"content":[{"type":"documentation","id":"2cd1a072-32a5-447c-8ca0-7448a25797ee","slug":"managing-api-keys","title":"Managing API Keys","url":"https://www.koji.so/docs/managing-api-keys","summary":"Guide to managing Koji API keys at Dashboard > Profile > API Keys. Covers creation, four permissions (interview:start, interview:chat, interview:complete, interview:read), key format (pk_live_), rotation, revocation, rate limiting, and security best practices.","content":"# Managing API Keys\n\nAPI 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.\n\n---\n\n## Where to Find API Key Management\n\nAPI keys are managed from your profile:\n\n1. Open the Koji dashboard.\n2. Navigate to **Dashboard > Profile > API Keys**.\n3. The **API Keys** section displays all keys across your projects.\n\nYou need project admin or owner permissions to manage API keys.\n\n---\n\n## Creating an API Key\n\nTo create a new key:\n\n1. Click **Create API Key** on the API Keys page.\n2. 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\").\n3. Select **permissions** for the key:\n   - `interview:start` -- Allows starting new interviews\n   - `interview:chat` -- Allows sending and receiving messages during an interview\n   - `interview:complete` -- Allows completing interviews and triggering analysis\n   - `interview:read` -- Allows retrieving interview data, transcripts, and analysis\n4. Click **Generate**.\n5. **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.\n\nStore 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.\n\n---\n\n## Permissions in Detail\n\nEach permission controls access to specific API endpoints:\n\n### interview:start\n\nAllows 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.\n\n### interview:chat\n\nAllows sending messages to an active interview session and receiving AI responses. This permission is required for any integration that manages the conversation flow programmatically.\n\n### interview:complete\n\nAllows calling `POST /api/v1/interviews/:id/complete`. This marks an interview as finished and triggers the automatic analysis pipeline.\n\n### interview:read\n\nAllows 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.\n\n### Combining Permissions\n\nMost integrations need all four permissions. However, the principle of least privilege suggests you only grant what is needed:\n\n- **Full integration** (start, chat, manage, retrieve): All four permissions.\n- **Read-only dashboard**: Only `interview:read`.\n- **Interview launcher**: `interview:start` and `interview:complete` (retrieval handled separately).\n- **Chat bot integration**: `interview:start`, `interview:chat`, and `interview:complete`.\n\nSee [API Authentication](/docs/api-authentication) for more details on how permissions work with the API.\n\n---\n\n## Viewing Existing Keys\n\nThe API Keys section lists all active keys:\n\n| Column | Description |\n|---|---|\n| Name | The descriptive name you assigned |\n| Key | Masked, showing only the key prefix |\n| Permissions | The permissions granted to this key |\n| Created | When the key was created |\n| Last Used | The most recent time the key was used in an API request |\n\nThe **Last Used** timestamp helps you identify inactive keys that may be candidates for revocation.\n\n---\n\n## Updating Key Settings\n\nYou can update key settings without generating a new key:\n\n1. Find the key in the list.\n2. Click the **Edit** button.\n3. Update the name, active status, allowed origins, or rate limit as needed.\n4. Click **Save**.\n\nChanges 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.\n\n---\n\n## Revoking a Key\n\nIf a key is compromised, no longer needed, or being rotated out:\n\n1. Find the key in the list.\n2. Click the **Revoke** button.\n3. Confirm the action in the dialog.\n\nRevocation 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.\n\n---\n\n## Key Rotation Best Practices\n\nRegular key rotation limits the damage if a key is ever exposed. Here is the recommended rotation process:\n\n1. **Create a new key** with the same permissions as the one you are replacing.\n2. **Update your application** to use the new key.\n3. **Verify the new key works** by monitoring API responses.\n4. **Revoke the old key** once you confirm the new key is active in all environments.\n\nDo not revoke the old key before confirming the new one works. Having two active keys simultaneously during rotation is expected and safe.\n\nA quarterly rotation schedule (every 90 days) is a good starting point for most teams.\n\n---\n\n## How Many Keys Should You Have\n\nThere is no strict limit on the number of API keys per project, but here are some guidelines:\n\n- **One key per environment.** Separate keys for development, staging, and production make it easy to revoke a key in one environment without affecting others.\n- **One key per service.** If multiple backend services call the Koji API, each should have its own key for easier auditing and independent revocation.\n- **Avoid sharing keys.** Never share a single key between multiple developers or services. Individual keys make access control and auditing possible.\n\n---\n\n## API Key Format\n\nKoji API keys follow the format `pk_live_` followed by 32 characters. For example:\n\n```\npk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345\n```\n\nWhen stored, only the first 12 characters (the prefix) are retained for identification. The full key is shown only once at creation time.\n\n---\n\n## Rate Limiting\n\nEach 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](/docs/rate-limits-and-cors) for details on headers and retry strategies.\n\n---\n\n## Security Best Practices\n\n- **Never commit keys to version control.** Use environment variables or a secrets manager.\n- **Set allowed origins.** Restrict which domains can use the key to prevent misuse if the key is exposed.\n- **Use the minimum permissions needed.** Grant only the permissions each integration actually requires.\n- **Monitor the Last Used timestamp.** Revoke keys that have not been used in 90+ days.\n- **Rotate keys quarterly.** Regular rotation limits exposure from undetected leaks.\n- **Use HTTPS only.** All API requests must use HTTPS. HTTP requests are rejected.\n\nFor more on API integration, see the [API Authentication](/docs/api-authentication) guide.","category":"Account & Settings","lastModified":"2026-04-25T19:14:08.521275+00:00","metaTitle":"Managing API Keys — Koji Docs","metaDescription":"Create, configure permissions, rotate, and revoke project-level API keys for Koji integrations.","keywords":["api keys","key management","permissions","key rotation","revoke api key"],"aiSummary":"Guide to managing Koji API keys at Dashboard > Profile > API Keys. Covers creation, four permissions (interview:start, interview:chat, interview:complete, interview:read), key format (pk_live_), rotation, revocation, rate limiting, and security best practices.","aiPrerequisites":["api-authentication"],"aiLearningOutcomes":["Create and configure API keys","Assign granular permissions","Rotate keys safely","Revoke compromised keys"],"aiDifficulty":"beginner","aiEstimatedTime":"6 min read"}],"pagination":{"total":1,"returned":1,"offset":0}}