kaneo (minimalist kanban) fork to experiment adding a tangled integration
github.com/usekaneo/kaneo
1---
2title: Authentication
3description: Learn how to authenticate API requests using API keys or the device authorization flow
4---
5
6
7All 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
16Use API keys when you control secret storage and want a stable credential for a single Kaneo instance.
17
18### Device authorization
19
20Use 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
22The device flow follows RFC 8628 and returns a Bearer token that can be used against that Kaneo instance's API.
23
24## Creating an API Key
25
26<Steps>
27<Step>
28**Sign in to Kaneo**
29
30Sign in to your Kaneo instance using your account credentials.
31</Step>
32
33<Step>
34**Navigate to Settings**
35
36Go to your account settings by clicking on your profile or navigating to the Settings page.
37</Step>
38
39<Step>
40**Open the Account Tab**
41
42In the Settings page, click on the **Account** tab to view your account settings.
43</Step>
44
45<Step>
46**Access API Keys Section**
47
48Scroll down to the **API Keys** section in the Account tab. This section is located under the Developer Settings.
49</Step>
50
51<Step>
52**Create a New API Key**
53
54Click the **Create API Key** button to generate a new API key. You'll be prompted to provide a name for your API key to help you identify it later.
55</Step>
56
57<Step>
58**Save Your API Key**
59
60After creating the API key, you'll be shown the full API key value. **Copy and save this key immediately** - it will not be shown again for security reasons.
61
62<Warning>
63**Important**: Store your API key securely. If you lose it, you'll need to create a new one. The API key cannot be retrieved after creation.
64</Warning>
65</Step>
66</Steps>
67
68## Using Your API Key
69
70Once you have your API key, include it in the `Authorization` header of all API requests using the Bearer token format:
71
72```bash
73Authorization: Bearer your-api-key-here
74```
75
76### Example Request
77
78Here's an example of making an authenticated API request using curl:
79
80```bash
81curl -X GET https://your-kaneo-instance.com/api/task?workspaceId=your-workspace-id \
82 -H "Authorization: Bearer your-api-key-here" \
83 -H "Content-Type: application/json"
84```
85
86### Example with JavaScript
87
88```javascript
89const response = await fetch('https://your-kaneo-instance.com/api/task?workspaceId=your-workspace-id', {
90 method: 'GET',
91 headers: {
92 'Authorization': 'Bearer your-api-key-here',
93 'Content-Type': 'application/json'
94 }
95});
96```
97
98## Using Device Authorization
99
100By default, self-hosted Kaneo allows the built-in device clients `kaneo-cli` and `kaneo-mcp`.
101
102If you want to use a different device client ID, the instance operator must allow it through `DEVICE_AUTH_CLIENT_IDS`.
103
104### Flow overview
105
1061. Your app requests a device code from `/api/auth/device/code`
1072. Kaneo returns a `device_code`, `user_code`, polling interval, and verification URL
1083. The user opens the verification URL in a browser and signs in
1094. The user approves the request
1105. Your app polls `/api/auth/device/token` until an access token is issued
1116. Your app sends API requests with `Authorization: Bearer <token>`
112
113### Request a device code
114
115```bash
116curl -X POST https://your-kaneo-instance.com/api/auth/device/code \
117 -H "Content-Type: application/json" \
118 -d '{"client_id":"your-app-id"}'
119```
120
121Example response:
122
123```json
124{
125 "device_code": "dev_123",
126 "user_code": "ABCD-1234",
127 "verification_uri": "https://your-kaneo-instance.com/device",
128 "verification_uri_complete": "https://your-kaneo-instance.com/device?user_code=ABCD-1234",
129 "interval": 5,
130 "expires_in": 600
131}
132```
133
134### Poll for a token
135
136```bash
137curl -X POST https://your-kaneo-instance.com/api/auth/device/token \
138 -H "Content-Type: application/json" \
139 -d '{
140 "grant_type":"urn:ietf:params:oauth:grant-type:device_code",
141 "device_code":"dev_123",
142 "client_id":"your-app-id"
143 }'
144```
145
146While waiting for approval, Kaneo may return:
147
148- `authorization_pending`
149- `slow_down`
150- `invalid_client`
151- `expired_token`
152
153Once approved, Kaneo returns an access token:
154
155```json
156{
157 "access_token": "your-access-token",
158 "token_type": "Bearer"
159}
160```
161
162### Use the returned token
163
164```bash
165curl -X GET https://your-kaneo-instance.com/api/task?workspaceId=your-workspace-id \
166 -H "Authorization: Bearer your-access-token"
167```
168
169## Security Best Practices
170
171- **Keep your API keys secret**: Never commit API keys to version control or share them publicly
172- **Use descriptive names**: Name your API keys clearly so you can identify their purpose (e.g., "Production Script", "Development Testing")
173- **Rotate keys regularly**: Periodically create new API keys and revoke old ones
174- **Limit key scope**: Only grant API keys to trusted applications and services
175- **Monitor usage**: Regularly review your API keys and remove any that are no longer needed
176- **Allow only trusted device clients**: Keep `DEVICE_AUTH_CLIENT_IDS` limited to approved client IDs on self-hosted deployments
177- **Treat Bearer device tokens like secrets**: Do not print or log them unnecessarily in production clients
178
179<Warning>
180If you suspect your API key has been compromised, immediately revoke it in the API Keys section and create a new one.
181</Warning>