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.

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.

---

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.

For a typical integration that starts interviews, waits for them to finish, and then retrieves results, you would grant all three permissions. For a read-only dashboard that simply displays completed interview data, interview:read 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 the complete endpoint.

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 /api/v1/interviews/:id/complete
Authorization: Bearer your_api_key_here
X-Session-Token: session_token_from_start_response

---

Plan Requirements

API access requires the Scale plan. The API is gated behind the headless_api feature flag. If you attempt to use an API key on a plan that does not include API access, you receive a 403 Forbidden response with a message indicating that your current plan does not support this feature.

Visit the plan comparison guide to see which plans include API access.

---

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.

It is good practice to rotate your API keys periodically, even if you do not suspect compromise. Create a new key, update your integration to use the new key, verify everything works, and then revoke the old key.

---

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
• Compare plans to confirm API access