Skip to content

armgit / kaneo

Public Imported from GitHub
0

⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.

feat(docs): add otp rfc 8628 to docs

Tin08a47a68cc24
diff --git a/ENVIRONMENT_SETUP.md b/ENVIRONMENT_SETUP.md
index 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 Variables
For local development, the web app also supports:
diff --git a/apps/docs/api-reference/authentication.mdx b/apps/docs/api-reference/authentication.mdx
index 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.mdx
index 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.