⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.
TypeScript honoissue-managementissue-trackerjira-alternativekanbanlinear-alternativemcpproject-managementreactself-hostedtypescript
feat(docs): add otp rfc 8628 to docs
Tin08a47a68cc24
diff --git a/ENVIRONMENT_SETUP.md b/ENVIRONMENT_SETUP.mdindex 69ad22f10..460cbfe3c 100644--- a/ENVIRONMENT_SETUP.md+++ b/ENVIRONMENT_SETUP.md@@ -26,11 +26,14 @@ For development, you'll need at minimum:- `KANEO_CLIENT_URL` - The URL of the web application (e.g., `http://localhost:5173`)- `KANEO_API_URL` - The URL of the API (e.g., `http://localhost:1337`)- `AUTH_SECRET` - Secret key for JWT token generation (**must be at least 32 characters long**; use a long, random value in production)+- `DEVICE_AUTH_CLIENT_IDS` - Optional comma-separated list of allowed device-flow client IDs (for example `kaneo-cli,my-app`)- `DATABASE_URL` - PostgreSQL connection string- `POSTGRES_DB` - PostgreSQL database name- `POSTGRES_USER` - PostgreSQL username- `POSTGRES_PASSWORD` - PostgreSQL password+If you are testing a CLI or external app against your local Kaneo instance, set `DEVICE_AUTH_CLIENT_IDS` to include the client ID your app sends to `/api/auth/device/code`.+### Development-Specific VariablesFor local development, the web app also supports:diff --git a/apps/docs/api-reference/authentication.mdx b/apps/docs/api-reference/authentication.mdxindex b9ef7c8d6..6bd044c7b 100644--- a/apps/docs/api-reference/authentication.mdx+++ b/apps/docs/api-reference/authentication.mdx@@ -1,10 +1,25 @@---title: Authentication-description: Learn how to authenticate API requests using API keys+description: Learn how to authenticate API requests using API keys or the device authorization flow----All API endpoints require authentication using an API key. This guide explains how to create an API key and use it to authenticate your requests.+All API endpoints require authentication. Kaneo currently supports two authentication patterns for API access:++- API keys for scripts, services, and long-lived integrations+- Device authorization for CLIs and external apps that need browser-based sign-in++## Choose an Authentication Method++### API keys++Use API keys when you control secret storage and want a stable credential for a single Kaneo instance.++### Device authorization++Use the device flow when you are building a CLI, desktop app, or other client that should send the user to the browser to approve access.++The device flow follows RFC 8628 and returns a Bearer token that can be used against that Kaneo instance's API.## Creating an API Key@@ -80,6 +95,75 @@ const response = await fetch('https://your-kaneo-instance.com/api/task?workspace});```+## Using Device Authorization++Before using device authorization on a self-hosted Kaneo instance, the instance operator must allow your client ID through `DEVICE_AUTH_CLIENT_IDS`.++### Flow overview++1. Your app requests a device code from `/api/auth/device/code`+2. Kaneo returns a `device_code`, `user_code`, polling interval, and verification URL+3. The user opens the verification URL in a browser and signs in+4. The user approves the request+5. Your app polls `/api/auth/device/token` until an access token is issued+6. Your app sends API requests with `Authorization: Bearer <token>`++### Request a device code++```bash+curl -X POST https://your-kaneo-instance.com/api/auth/device/code \+ -H "Content-Type: application/json" \+ -d '{"client_id":"your-app-id"}'+```++Example response:++```json+{+ "device_code": "dev_123",+ "user_code": "ABCD-1234",+ "verification_uri": "https://your-kaneo-instance.com/device",+ "verification_uri_complete": "https://your-kaneo-instance.com/device?user_code=ABCD-1234",+ "interval": 5,+ "expires_in": 600+}+```++### Poll for a token++```bash+curl -X POST https://your-kaneo-instance.com/api/auth/device/token \+ -H "Content-Type: application/json" \+ -d '{+ "grant_type":"urn:ietf:params:oauth:grant-type:device_code",+ "device_code":"dev_123",+ "client_id":"your-app-id"+ }'+```++While waiting for approval, Kaneo may return:++- `authorization_pending`+- `slow_down`+- `invalid_client`+- `expired_token`++Once approved, Kaneo returns an access token:++```json+{+ "access_token": "your-access-token",+ "token_type": "Bearer"+}+```++### Use the returned token++```bash+curl -X GET https://your-kaneo-instance.com/api/task?workspaceId=your-workspace-id \+ -H "Authorization: Bearer your-access-token"+```+## Security Best Practices- **Keep your API keys secret**: Never commit API keys to version control or share them publicly@@ -87,6 +171,8 @@ const response = await fetch('https://your-kaneo-instance.com/api/task?workspace- **Rotate keys regularly**: Periodically create new API keys and revoke old ones- **Limit key scope**: Only grant API keys to trusted applications and services- **Monitor usage**: Regularly review your API keys and remove any that are no longer needed+- **Allow only trusted device clients**: Keep `DEVICE_AUTH_CLIENT_IDS` limited to approved client IDs on self-hosted deployments+- **Treat Bearer device tokens like secrets**: Do not print or log them unnecessarily in production clients<Warning>If you suspect your API key has been compromised, immediately revoke it in the API Keys section and create a new one.diff --git a/apps/docs/core/installation/environment-variables.mdx b/apps/docs/core/installation/environment-variables.mdxindex 06b9bf242..91595b5fa 100644--- a/apps/docs/core/installation/environment-variables.mdx+++ b/apps/docs/core/installation/environment-variables.mdx@@ -50,6 +50,7 @@ This section will cover all the variables related to the authentication.Name | Description |--- | --- || `AUTH_SECRET` | The secret key for the JWT token. **Must be at least 32 characters long**, use a long, random value in production. Example: use `openssl rand -base64 32` to generate a secure key in Linux/macOS.+| `DEVICE_AUTH_CLIENT_IDS` | Comma-separated list of allowed device authorization client IDs. Use this to permit trusted CLI or external app identifiers such as `kaneo-cli,my-desktop-app`. |## Optional variables@@ -138,3 +139,4 @@ Name | Description |- If you enable Discord SSO, you need to set up the Discord application which is used to authenticate users in the [Discord Developer Portal](https://discord.com/developers/applications). See the [Discord SSO guide](/core/social-providers/discord).- If you enable Custom OAuth/OIDC, you need to configure your identity provider with the appropriate redirect URI. See the [Custom OAuth/OIDC guide](/core/social-providers/custom-oauth).- If you have enabled SMTP, your sign in will be done via email using a magic link.+- If you want to allow CLI or external-app sign-in through device authorization, set `DEVICE_AUTH_CLIENT_IDS` to the trusted client IDs for your deployment.