Kaneo API Authentication Methods: 5 Ways to Secure API Requests

Kaneo supports five distinct API authentication mechanisms—session-cookie authentication via Better-Auth, Bearer token authentication, API key authentication, device authorization flow, and OAuth 2.0 providers—all unified through centralized middleware in apps/api/src/utils/authenticate-api-request.ts.

The usekaneo/kaneo repository implements a flexible, multi-layered authentication surface designed to accommodate both interactive web sessions and headless programmatic access. Understanding these Kaneo API authentication methods enables developers to select the appropriate credential type for their specific integration scenario, whether building a browser-based client, a mobile application, or a server-side automation script.

Session-Cookie Authentication via Better-Auth

Kaneo uses Better-Auth as its primary identity framework, configured in apps/api/src/auth.ts. This method Issues a JWT after successful sign-in through multiple strategies including magic-link, email-OTP, password-based login, or OAuth providers.

The JWT is stored in an HttpOnly cookie, which the browser automatically transmits with each request. This approach protects against XSS attacks while maintaining seamless session continuity for web clients. The configuration in apps/api/src/auth.ts registers all authentication plugins and establishes the session cookie parameters.

Bearer Token Authentication

For programmatic clients that cannot rely on browser cookie storage, Kaneo supports explicit Bearer token authentication. Clients pass a valid JWT in the Authorization: Bearer <token> header.

This implementation resides in apps/api/src/utils/authenticate-api-request.ts, where the middleware extracts the token from the Authorization header and performs validation before passing the request downstream. This method is ideal for server-to-server integrations and API testing tools.

curl -H "Authorization: Bearer <jwt-token>" \
     https://kaneo.example.com/api/v1/tasks

API Key Authentication

Kaneo implements API key authentication for long-lived, workspace-scoped access. Users generate secret keys that are transmitted via the x-api-key header. Unlike temporary JWTs, these keys persist until explicitly revoked and can carry specific rate-limit settings and permissions.

The header parsing logic exists in apps/api/src/utils/authenticate-api-request.ts, while the actual verification—including database lookups, validity checks, and rate-limit enforcement—occurs in apps/api/src/utils/verify-api-key.ts. The middleware populates c.get("apiKey") for downstream handlers, enabling fine-grained workspace authorization as demonstrated in apps/api/src/utils/workspace-access-middleware.ts.

curl -H "x-api-key: <your-api-key>" \
     https://kaneo.example.com/api/v1/tasks

Device Authorization Flow

For devices lacking browser capabilities—such as CLI tools or embedded systems—Kaneo supports the device authorization flow. This OAuth 2.0 extension allows clients to obtain a device code and poll for an access token without requiring user agent redirection.

The flow is registered via the deviceAuthorization plugin in apps/api/src/auth.ts. Clients first request a device code from the /api/auth/device endpoint, then poll /api/auth/token until the user completes authorization on a separate device.

# 1️⃣ Request a device code

curl -X POST https://kaneo.example.com/api/auth/device \
     -d '{"client_id":"kaneo-cli"}'

# 2️⃣ Poll for a token

curl -X POST https://kaneo.example.com/api/auth/token \
     -d '{"device_code":"<code>", "client_id":"kaneo-cli"}'

OAuth 2.0 Provider Integration

Kaneo enables authentication through external identity providers—such as GitHub, Google, or other OAuth 2.0 services—via the genericOAuth plugin configured in apps/api/src/auth.ts. After the OAuth callback completes, the system issues a JWT for the authenticated user.

The system maps provider-specific profile data to Kaneo user records using apps/api/src/utils/custom-oauth-profile.ts. This abstraction layer normalizes attributes across different identity providers, ensuring consistent user creation and linking regardless of the external service used.

The Central Authentication Middleware

All authentication methods converge in a single authentication middleware located at apps/api/src/utils/authenticate-api-request.ts. This middleware performs credential detection—checking for cookies, Bearer tokens, or API keys—then validates the presented credential and injects the authenticated context into the Hono request context.

Specifically, the middleware populates c.get("user") for session and Bearer-based requests, and c.get("apiKey") for key-based requests. Downstream handlers, including workspace access controls in apps/api/src/utils/workspace-access-middleware.ts, consume these values to enforce authorization policies.

Summary

• Session-cookie authentication leverages Better-Auth in apps/api/src/auth.ts to provide secure, browser-based sessions using HttpOnly cookies.
• Bearer token authentication allows programmatic clients to authenticate via the Authorization header, validated in apps/api/src/utils/authenticate-api-request.ts.
• API key authentication uses the x-api-key header for persistent, workspace-scoped access, with verification logic split between authenticate-api-request.ts and verify-api-key.ts.
• Device authorization flow enables CLI and IoT device authentication through device codes and polling endpoints, registered in the main auth configuration.
• OAuth 2.0 integration supports external providers through the genericOAuth plugin and custom profile mapping utilities.

Frequently Asked Questions

How do I send authenticated requests using a Bearer token in Kaneo?

Pass a valid JWT in the Authorization header using the format Bearer <token>. The middleware in apps/api/src/utils/authenticate-api-request.ts extracts and validates this token, populating c.get("user") for downstream route handlers to identify the requesting user.

What is the difference between API key and Bearer token authentication in Kaneo?

Bearer tokens are short-lived JWTs obtained through login flows, suitable for temporary session management. API keys are long-lived secrets stored in the database, scoped to specific workspaces, and subject to custom rate limits and permissions defined in apps/api/src/utils/verify-api-key.ts.

Where does Kaneo validate API key permissions and rate limits?

The system validates API key permissions, expiration dates, and rate-limit settings in apps/api/src/utils/verify-api-key.ts. This utility is invoked by the main authentication middleware after parsing the x-api-key header, ensuring that only active, authorized keys proceed to workspace-scoped resources.

Can CLI tools authenticate with Kaneo without opening a browser?

Yes. CLI tools should implement the device authorization flow, which uses the deviceAuthorization plugin defined in apps/api/src/auth.ts. The tool requests a device code, displays a user verification URL, and polls the token endpoint until the user authorizes the device through a separate browser session.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}