API Authentication

Every request to the Koji API must include a valid API key passed as a Bearer token. Without proper authentication, the API returns a 401 Unauthorized response.

---

How Authentication Works

Koji uses API keys to authenticate requests to its REST API. Each key is scoped to a specific project and carries a set of permissions that control what operations it can perform. When you make a request, include your API key in the Authorization header:

Authorization: Bearer your_api_key_here

The API validates your key on every request, checks that the key has the required permissions for the endpoint you are calling, and verifies that the key has not been revoked. If any of these checks fail, you receive an error response with details about what went wrong.

---

Creating an API Key

API keys are created from the Integrations page within your project settings. Here is how to generate one:

1. Open the project you want to integrate with.
2. Navigate to Settings > Integrations.
3. Click Create API Key.
4. Give the key a descriptive name (for example, "Production Backend" or "Staging Test Key").
5. Select the permissions the key needs (see the Permissions section below).
6. Click Generate.
7. Copy the key immediately. For security, Koji only displays the full key once at creation time.

API keys use the pk_live_ prefix followed by 32 cryptographically random characters. The key is stored as a SHA-256 hash, so it cannot be retrieved after creation.

Store your API key securely. Treat it like a password. Never commit it to source control, embed it in client-side code, or share it in plain text. For more on key lifecycle management, see Managing API Keys.

---

Permissions

Each API key can be granted one or more permissions. This follows the principle of least privilege — only grant the permissions your integration actually needs.

By default, new API keys are created with all four permissions. For a typical integration that starts interviews, exchanges messages, and then retrieves results, all four permissions are appropriate. For a read-only dashboard that simply displays completed interview data, interview:read alone is sufficient.

You can update permissions on an existing key at any time from the Integrations page without regenerating the key itself.

---

Session Tokens

Some endpoints use a secondary authentication mechanism called a session token. When you start an interview via the API, the response includes a session_token. This token is tied to that specific interview session and is required when calling certain endpoints like sending messages and the complete endpoint.

<figure class="koji-figure"> <img src="https://sybpuenocntpoywqhgkf.supabase.co/storage/v1/object/public/blog-images/api-authentication/inline-tokens-comparison.webp" alt="API key versus session token comparison for the Koji headless API across scope, lifetime, header and creation steps." title="API key vs session token" width="800" height="401" loading="lazy" /> <figcaption> <span class="caption-text">How API keys and session tokens differ across scope, lifetime, header and the way each is created.</span> <span class="caption-source">Koji headless API documentation</span> </figcaption> </figure>

Session tokens differ from API keys in important ways:

• Scope: A session token is valid only for the single interview it was created for.
• Lifetime: Session tokens expire when the interview is completed or after a period of inactivity.
• Header: Pass the session token using the X-Session-Token header, not the Authorization header.

A typical request using both authentication methods looks like this:

POST https://koji.so/api/v1/interviews/:id/message
Authorization: Bearer your_api_key_here
X-Session-Token: session_token_from_start_response

---

Plan Requirements

API access is available on all Koji plans, including the free tier. The API is gated behind the headless_api entitlement, which is enabled for every plan. You can start building your integration immediately after creating a project.

---

Rate Limiting

Each API key has a default rate limit of 60 requests per minute. Every response includes rate limit headers so you can monitor your usage:

When you exceed the limit, the API returns a 429 Too Many Requests response. For detailed guidance on handling rate limits, see Rate Limits and CORS.

---

Revoking Keys

If you suspect a key has been compromised, revoke it immediately:

1. Go to Settings > Integrations in your project.
2. Find the key in the list.
3. Click the Revoke button.
4. Confirm the action.

Revocation is instant. Any in-flight requests using that key will fail. There is no undo — if you need API access again, create a new key.

You can also deactivate a key temporarily by setting its is_active field to false, which lets you re-enable it later without regenerating. It is good practice to rotate your API keys periodically, even if you do not suspect compromise.

---

Error Responses

Authentication errors return standard HTTP status codes:

The response body includes a JSON object with an error field and a human-readable message field to help you diagnose the issue.

{
  "error": "unauthorized",
  "message": "The provided API key is invalid or has been revoked."
}

---

Security Best Practices

Following these practices protects your integration and your respondents' data:

• Never expose keys client-side. API keys belong on your server. If you need browser-based access, proxy requests through your backend.
• Use environment variables. Store keys in environment variables or a secrets manager, not in your codebase.
• Scope permissions tightly. Grant only the permissions each key actually needs.
• Rotate regularly. Set a calendar reminder to rotate keys every 90 days.
• Monitor usage. Review your API usage in the project dashboard to spot unusual patterns.
• Revoke unused keys. If a key is no longer needed, revoke it. Orphaned keys are a security risk.

For more on securing your API integration, see Rate Limits and CORS.

---

Next Steps

• Start your first interview via the API
• Understand rate limits and CORS configuration
• Learn about managing API keys
• Explore the headless API overview