kaneo (minimalist kanban) fork to experiment adding a tangled integration
github.com/usekaneo/kaneo
feat(docs): add otp rfc 8628 to docs
+93
-2
+3
ENVIRONMENT_SETUP.md
+3
ENVIRONMENT_SETUP.md
···
26
26
- `KANEO_CLIENT_URL` - The URL of the web application (e.g., `http://localhost:5173`)
27
27
- `KANEO_API_URL` - The URL of the API (e.g., `http://localhost:1337`)
28
28
- `AUTH_SECRET` - Secret key for JWT token generation (**must be at least 32 characters long**; use a long, random value in production)
29
+
- `DEVICE_AUTH_CLIENT_IDS` - Optional comma-separated list of allowed device-flow client IDs (for example `kaneo-cli,my-app`)
29
30
- `DATABASE_URL` - PostgreSQL connection string
30
31
- `POSTGRES_DB` - PostgreSQL database name
31
32
- `POSTGRES_USER` - PostgreSQL username
32
33
- `POSTGRES_PASSWORD` - PostgreSQL password
34
+
35
+
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`.
33
36
34
37
### Development-Specific Variables
35
38
+88
-2
apps/docs/api-reference/authentication.mdx
+88
-2
apps/docs/api-reference/authentication.mdx
···
1
1
---
2
2
title: Authentication
3
-
description: Learn how to authenticate API requests using API keys
3
+
description: Learn how to authenticate API requests using API keys or the device authorization flow
4
4
---
5
5
6
6
7
-
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.
7
+
All API endpoints require authentication. Kaneo currently supports two authentication patterns for API access:
8
+
9
+
- API keys for scripts, services, and long-lived integrations
10
+
- Device authorization for CLIs and external apps that need browser-based sign-in
11
+
12
+
## Choose an Authentication Method
13
+
14
+
### API keys
15
+
16
+
Use API keys when you control secret storage and want a stable credential for a single Kaneo instance.
17
+
18
+
### Device authorization
19
+
20
+
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.
21
+
22
+
The device flow follows RFC 8628 and returns a Bearer token that can be used against that Kaneo instance's API.
8
23
9
24
## Creating an API Key
10
25
···
80
95
});
81
96
```
82
97
98
+
## Using Device Authorization
99
+
100
+
Before using device authorization on a self-hosted Kaneo instance, the instance operator must allow your client ID through `DEVICE_AUTH_CLIENT_IDS`.
101
+
102
+
### Flow overview
103
+
104
+
1. Your app requests a device code from `/api/auth/device/code`
105
+
2. Kaneo returns a `device_code`, `user_code`, polling interval, and verification URL
106
+
3. The user opens the verification URL in a browser and signs in
107
+
4. The user approves the request
108
+
5. Your app polls `/api/auth/device/token` until an access token is issued
109
+
6. Your app sends API requests with `Authorization: Bearer <token>`
110
+
111
+
### Request a device code
112
+
113
+
```bash
114
+
curl -X POST https://your-kaneo-instance.com/api/auth/device/code \
115
+
-H "Content-Type: application/json" \
116
+
-d '{"client_id":"your-app-id"}'
117
+
```
118
+
119
+
Example response:
120
+
121
+
```json
122
+
{
123
+
"device_code": "dev_123",
124
+
"user_code": "ABCD-1234",
125
+
"verification_uri": "https://your-kaneo-instance.com/device",
126
+
"verification_uri_complete": "https://your-kaneo-instance.com/device?user_code=ABCD-1234",
127
+
"interval": 5,
128
+
"expires_in": 600
129
+
}
130
+
```
131
+
132
+
### Poll for a token
133
+
134
+
```bash
135
+
curl -X POST https://your-kaneo-instance.com/api/auth/device/token \
136
+
-H "Content-Type: application/json" \
137
+
-d '{
138
+
"grant_type":"urn:ietf:params:oauth:grant-type:device_code",
139
+
"device_code":"dev_123",
140
+
"client_id":"your-app-id"
141
+
}'
142
+
```
143
+
144
+
While waiting for approval, Kaneo may return:
145
+
146
+
- `authorization_pending`
147
+
- `slow_down`
148
+
- `invalid_client`
149
+
- `expired_token`
150
+
151
+
Once approved, Kaneo returns an access token:
152
+
153
+
```json
154
+
{
155
+
"access_token": "your-access-token",
156
+
"token_type": "Bearer"
157
+
}
158
+
```
159
+
160
+
### Use the returned token
161
+
162
+
```bash
163
+
curl -X GET https://your-kaneo-instance.com/api/task?workspaceId=your-workspace-id \
164
+
-H "Authorization: Bearer your-access-token"
165
+
```
166
+
83
167
## Security Best Practices
84
168
85
169
- **Keep your API keys secret**: Never commit API keys to version control or share them publicly
···
87
171
- **Rotate keys regularly**: Periodically create new API keys and revoke old ones
88
172
- **Limit key scope**: Only grant API keys to trusted applications and services
89
173
- **Monitor usage**: Regularly review your API keys and remove any that are no longer needed
174
+
- **Allow only trusted device clients**: Keep `DEVICE_AUTH_CLIENT_IDS` limited to approved client IDs on self-hosted deployments
175
+
- **Treat Bearer device tokens like secrets**: Do not print or log them unnecessarily in production clients
90
176
91
177
<Warning>
92
178
If you suspect your API key has been compromised, immediately revoke it in the API Keys section and create a new one.
+2
apps/docs/core/installation/environment-variables.mdx
+2
apps/docs/core/installation/environment-variables.mdx
···
50
50
Name | Description |
51
51
--- | --- |
52
52
| `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.
53
+
| `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`. |
53
54
54
55
55
56
## Optional variables
···
138
139
- 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).
139
140
- 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).
140
141
- If you have enabled SMTP, your sign in will be done via email using a magic link.
142
+
- 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.