Authentifizierung

Die Kanman API verwendet API-Token (auch bekannt als API-Schlüssel) zur Authentifizierung. Jede Anfrage an die API muss einen gültigen Token enthalten, der Ihr Konto identifiziert und bestimmt, welche Operationen Sie ausführen dürfen. Dieser Leitfaden behandelt alles, was Sie über das Erstellen, Verwenden und Sichern Ihrer API-Token wissen müssen.

API-Token sind mit Sicherheit im Fokus konzipiert. Sie sind auf bestimmte Berechtigungen beschränkt, haben obligatorische Ablaufdaten und können bei Kompromittierung sofort widerrufen werden. Dies gibt Ihnen feinkörnige Kontrolle darüber, worauf jede Integration zugreifen kann, während es einfach bleibt, Anmeldedaten regelmäßig zu rotieren.

Desktop Mobile

API-Token-Format

Kanman API-Token:

• Beginnen mit dem Präfix km_
• Sind insgesamt 35 Zeichen lang (km_ + 32 zufällige Zeichen)
• Beispiel: km_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdef

Das Präfix macht es einfach, Kanman-Token in Ihrem Code oder Ihrer Konfiguration zu identifizieren, während die zufälligen Zeichen ausreichende Entropie für die Sicherheit bieten.

API-Token erstellen

Das Erstellen eines Tokens dauert nur wenige Sekunden. Stellen Sie sicher, dass Sie bereit sind, das Token sofort zu kopieren und zu speichern – es wird nur einmal angezeigt.

1. Gehen Sie zu Einstellungen > API-Token
2. Klicken Sie auf Token erstellen
3. Geben Sie einen beschreibenden Namen ein (z.B. “CI/CD Pipeline”, “Zapier Integration”)
4. Wählen Sie die benötigten Berechtigungsbereiche
5. Legen Sie ein Ablaufdatum fest (max. 365 Tage)
6. Klicken Sie auf Erstellen

Desktop Mobile

Wichtig: Das Token wird nur einmal angezeigt. Kopieren und speichern Sie es sofort sicher.

Desktop Mobile

Token-Berechtigungen

Berechtigungsbereiche bestimmen, welche Aktionen ein Token ausführen kann. Nach dem Prinzip der geringsten Privilegien sollten Sie nur die Berechtigungen gewähren, die Ihre Integration tatsächlich benötigt. Dies begrenzt potenziellen Schaden bei einer Token-Kompromittierung und erleichtert die Überprüfung, was verschiedene Integrationen tun können.

Token können einen oder mehrere Berechtigungsbereiche haben:

Im Zweifelsfall beginnen Sie mit minimalen Berechtigungen und erweitern Sie diese nur bei Berechtigungsfehlern. Sie können jederzeit einen neuen Token mit zusätzlichen Berechtigungen erstellen.

Berechtigungsbeispiele

Ihr Token verwenden

Fügen Sie das Token im Authorization-Header ein:

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

JavaScript-Beispiel

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

Python-Beispiel

import requests

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

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

Token-Eigenschaften

Jedes Token hat folgende Eigenschaften:

Token-Limits

Kaufen Sie bei Bedarf zusätzliche Token-Pakete.

Token-Ablauf

Token müssen ein Ablaufdatum haben:

• Minimum: 1 Tag ab Erstellung
• Maximum: 365 Tage ab Erstellung
• Empfehlung: Verwenden Sie die kürzeste praktikable Ablaufzeit

Abgelaufene Token werden mit einem 401 Unauthorized-Fehler abgelehnt.

Token widerrufen

Um ein Token zu widerrufen:

1. Gehen Sie zu Einstellungen > API-Token
2. Finden Sie das Token nach Name oder Präfix
3. Klicken Sie auf Widerrufen
4. Bestätigen Sie den Widerruf

Desktop Mobile

Widerrufene Token sind sofort ungültig.

Token-Sicherheit

Sicherheit ist beim Arbeiten mit API-Token kritisch. Ein kompromittiertes Token gibt Angreifern denselben Zugriff wie Ihre Integration, daher sollte der Schutz Ihrer Token höchste Priorität haben. Das Befolgen dieser Best Practices minimiert Risiken und erleichtert die Reaktion bei Problemen.

Best Practices

1. Token niemals in Versionskontrolle committen

   • Verwenden Sie Umgebungsvariablen für lokale Entwicklung
   • Verwenden Sie Secret-Management-Tools für Produktion
   • Fügen Sie .env-Dateien zu Ihrer .gitignore hinzu

2. Minimale Berechtigungen verwenden

   • Nur tatsächlich benötigte Berechtigungen gewähren
   • Separate Token für verschiedene Zwecke erstellen
   • Ein Reporting-Dashboard benötigt nur read, nicht admin

3. Regelmäßig rotieren

   • Erinnerungen vor Ablauf setzen
   • Neues Token erstellen, bevor das alte widerrufen wird
   • Kürzere Ablaufperioden reduzieren Risikofenster

4. Nutzung überwachen

   • last_used_at auf unerwartete Aktivität prüfen
   • Ungenutzte Token zeitnah widerrufen
   • Verdächtige Zugriffsmuster untersuchen

Was Sie NICHT tun sollten

• ❌ Token zwischen Teammitgliedern teilen
• ❌ Token mit admin-Berechtigung unnötig verwenden
• ❌ Token in Client-seitigem Code speichern
• ❌ Token über unverschlüsselte Kanäle senden

Token-Speicherung

Speichern Sie Token sicher:

Umgebungsvariablen

export KANMAN_API_TOKEN=km_ihr_api_token

const token = process.env.KANMAN_API_TOKEN;

Secret Manager

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

CI/CD-Systeme

Die meisten CI/CD-Systeme unterstützen Secrets:

• GitHub Actions: Repository-Secrets
• GitLab CI: CI/CD-Variablen
• Jenkins: Credentials-Plugin

Authentifizierungsfehler

Beispiel: Kompletter Ablauf

// 1. Token in Umgebung speichern
// export KANMAN_API_TOKEN=km_xxxxx

// 2. Im Code verwenden
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-Fehler: ${response.status}`);
  }

  return response.json();
}

// 3. Die Funktion verwenden
const task = await createTask('project-uuid', 'Neue Aufgabe über API');
console.log(task);

Verwandte Themen

• Rate-Limits - API-Kontingente
• Fehler - Fehlerbehandlung
• Boards - Board-Endpunkte