# Kaneo API Authentication Methods: 5 Ways to Secure API Requests > Discover Kaneo API authentication methods. Explore session-cookie, Bearer token, API key, device authorization, and OAuth 2.0 for secure API requests. - Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo) - Tags: api-reference - Published: 2026-08-29 --- **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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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 ` header. This implementation resides in [`apps/api/src/utils/authenticate-api-request.ts`](https://github.com/usekaneo/kaneo/blob/main/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. ```bash curl -H "Authorization: Bearer " \ 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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/utils/workspace-access-middleware.ts). ```bash curl -H "x-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`](https://github.com/usekaneo/kaneo/blob/main/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. ```bash # 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":"", "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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/authenticate-api-request.ts) and [`verify-api-key.ts`](https://github.com/usekaneo/kaneo/blob/main/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 `. The middleware in [`apps/api/src/utils/authenticate-api-request.ts`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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.