workboardworkboard

Authentication

All API endpoints require authentication. Workboard 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 Workboard 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 Workboard instance's API.

Creating an API Key

Sign in to Workboard

Sign in to your Workboard instance using your account credentials.

Navigate to Settings

Go to your account settings by clicking on your profile or navigating to the Settings page.

Open the Account Tab

In the Settings page, click on the Account tab to view your account settings.

Access API Keys Section

Scroll down to the API Keys section in the Account tab. This section is located under the Developer Settings.

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.

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.

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 Workboard allows the built-in device clients workboard-cli and workboard-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. Workboard 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, Workboard may return:

  • authorization_pending
  • slow_down
  • invalid_client
  • expired_token

Once approved, Workboard 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.