> ## Documentation Index
> Fetch the complete documentation index at: https://kaneo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to authenticate API requests using API keys or the device authorization flow

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

<Steps>
  <Step>
    **Sign in to Kaneo**

    Sign in to your Kaneo instance using your account credentials.
  </Step>

  <Step>
    **Navigate to Settings**

    Go to your account settings by clicking on your profile or navigating to the Settings page.
  </Step>

  <Step>
    **Open the Account Tab**

    In the Settings page, click on the **Account** tab to view your account settings.
  </Step>

  <Step>
    **Access API Keys Section**

    Scroll down to the **API Keys** section in the Account tab. This section is located under the Developer Settings.
  </Step>

  <Step>
    **Create a New API Key**

    Click 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.
  </Step>

  <Step>
    **Save Your API Key**

    After 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.

    <Warning>
      **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.
    </Warning>
  </Step>
</Steps>

## 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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
Authorization: Bearer your-api-key-here
```

### Example Request

Here's an example of making an authenticated API request using curl:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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

```javascript theme={"theme":{"light":"min-light","dark":"min-dark"}}
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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "access_token": "your-access-token",
  "token_type": "Bearer"
}
```

### Use the returned token

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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

<Warning>
  If you suspect your API key has been compromised, immediately revoke it in the API Keys section and create a new one.
</Warning>