Authentication

The Kanman API uses API tokens (also known as API keys) for authentication. Every request to the API must include a valid token, which identifies your account and determines what operations you’re allowed to perform. This guide covers everything you need to know about creating, using, and securing your API tokens.

API tokens are designed with security in mind. They’re scoped to specific permissions, have mandatory expiration dates, and can be revoked instantly if compromised. This gives you fine-grained control over what each integration can access while making it easy to rotate credentials regularly.

Desktop Mobile

API Token Format

Kanman API tokens:

• Start with the prefix km_
• Are 35 characters total (km_ + 32 random characters)
• Example: km_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdef

Creating an API Token

1. Go to Settings > API Tokens
2. Click Create Token
3. Enter a descriptive name (e.g., “CI/CD Pipeline”, “Zapier Integration”)
4. Select the scopes you need
5. Set an expiration date (max 365 days)
6. Click Create

Desktop Mobile

Important: The token is only shown once. Copy and store it securely immediately.

Desktop Mobile

Token Scopes

Scopes determine what actions a token can perform. Following the principle of least privilege, you should only grant the permissions your integration actually needs. This limits potential damage if a token is ever compromised and makes it easier to audit what different integrations can do.

Tokens can have one or more scopes:

When in doubt, start with minimal scopes and expand them only if you encounter permission errors. You can always create a new token with additional scopes.

Scope Examples

Using Your Token

Include the token in the Authorization header:

curl https://api.kanman.de/v1/boards \
  -H "Authorization: Bearer km_your_api_token"

JavaScript Example

const response = await fetch('https://api.kanman.de/v1/boards', {
  headers: {
    'Authorization': 'Bearer km_your_api_token',
    'Content-Type': 'application/json'
  }
});
const data = await response.json();

Python Example

import requests

headers = {
    'Authorization': 'Bearer km_your_api_token',
    'Content-Type': 'application/json'
}

response = requests.get('https://api.kanman.de/v1/boards', headers=headers)
data = response.json()

Token Properties

Each token has:

Token Limits

Purchase additional token packs if needed.

Token Expiration

Tokens must have an expiration date:

• Minimum: 1 day from creation
• Maximum: 365 days from creation
• Recommendation: Use the shortest practical expiration

Expired tokens are rejected with a 401 Unauthorized error.

Revoking Tokens

To revoke a token:

1. Go to Settings > API Tokens
2. Find the token by name or prefix
3. Click Revoke
4. Confirm revocation

Desktop Mobile

Revoked tokens are immediately invalid.

Token Security

Security is critical when working with API tokens. A compromised token gives attackers the same access your integration has, so protecting your tokens should be a top priority. Following these best practices helps minimize risk and makes it easier to respond if something goes wrong.

Best Practices

1. Never commit tokens to version control

   • Use environment variables for local development
   • Use secret management tools for production
   • Add .env files to your .gitignore

2. Use minimal scopes

   • Only grant permissions actually needed
   • Create separate tokens for different purposes
   • A reporting dashboard only needs read, not admin

3. Rotate regularly

   • Set reminders before expiration
   • Create new token before revoking old one
   • Shorter expiration periods reduce risk windows

4. Monitor usage

   • Check last_used_at for unexpected activity
   • Revoke unused tokens promptly
   • Investigate any suspicious access patterns

What NOT to Do

• ❌ Share tokens between team members
• ❌ Use tokens with admin scope unnecessarily
• ❌ Store tokens in client-side code
• ❌ Send tokens over unencrypted channels

Token Storage

Store tokens securely:

Environment Variables

export KANMAN_API_TOKEN=km_your_api_token

const token = process.env.KANMAN_API_TOKEN;

Secret Managers

• AWS Secrets Manager
• HashiCorp Vault
• Azure Key Vault
• Google Secret Manager

CI/CD Systems

Most CI/CD systems support secrets:

• GitHub Actions: Repository secrets
• GitLab CI: CI/CD variables
• Jenkins: Credentials plugin

Authentication Errors

Example: Complete Flow

// 1. Store token in environment
// export KANMAN_API_TOKEN=km_xxxxx

// 2. Use in code
const KANMAN_TOKEN = process.env.KANMAN_API_TOKEN;

async function createTask(projectId, label) {
  const response = await fetch('https://api.kanman.de/v1/tasks', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${KANMAN_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      projectId,
      label
    })
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

// 3. Use the function
const task = await createTask('project-uuid', 'New task from API');
console.log(task);

Related Topics

• Rate Limits - API quotas
• Errors - Error handling
• Boards - Board endpoints