Skip to main content
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

1
Sign in to KaneoSign in to your Kaneo instance using your account credentials.
2
Navigate to SettingsGo to your account settings by clicking on your profile or navigating to the Settings page.
3
Open the Account TabIn the Settings page, click on the Account tab to view your account settings.
4
Access API Keys SectionScroll down to the API Keys section in the Account tab. This section is located under the Developer Settings.
5
Create a New API KeyClick 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.
6
Save Your API KeyAfter 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.
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.

​
Using Your API Key

Once you have your API key, include it in the Authorization header of all API requests using the Bearer token format: 
Authorization: Bearer your-api-key-here

​
Example Request

Here’s an example of making an authenticated API request using curl: 
curl -X GET https://your-kaneo-instance.com/api/task?workspaceId=your-workspace-id \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json"

​
Example with JavaScript

const response = await fetch('https://your-kaneo-instance.com/api/task?workspaceId=your-workspace-id', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your-api-key-here',
    'Content-Type': 'application/json'
  }
});

​
Using Device Authorization

By default, self-hosted Kaneo allows the built-in device clients kaneo-cli and kaneo-mcp. If you want to use a different device client ID, the instance operator must allow it 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

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: 
{
  "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

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: 
{
  "access_token": "your-access-token",
  "token_type": "Bearer"
}

​
Use the returned token

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
  • Use descriptive names: Name your API keys clearly so you can identify their purpose (e.g., “Production Script”, “Development Testing”)
  • 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
If you suspect your API key has been compromised, immediately revoke it in the API Keys section and create a new one.