API-Schlüssel

Erfahren Sie, wie Sie die Authentifizierung für CLI und API-Zugriff in TeamDay verwalten.

Inhaltsverzeichnis

Authentifizierungsmethoden

TeamDay unterstützt zwei Authentifizierungsmethoden:

MethodeAnwendungsfallAblaufAm besten für
OAuth 2.1CLI interaktive Nutzung15 min (Access Token)
90 Tage (Refresh Token)		Menschliche Benutzer, Entwicklung
Personal Access Token (PAT)API-AutomatisierungNur manuelle WiderrufCI/CD, Skripte, Automatisierung

OAuth vs PAT

Verwenden Sie OAuth, wenn:

  • Sie interaktiv mit CLI arbeiten
  • Sie ein menschlicher Benutzer sind
  • Sie automatische Token-Aktualisierung möchten
  • Kurzfristiger Zugriff bevorzugt wird

Verwenden Sie PAT, wenn:

  • Sie mit Skripten oder CI/CD automatisieren
  • Hintergrund-Jobs ausführen
  • Langfristiger Zugriff benötigt wird
  • Einfache Bearer Token Auth gewünscht ist

Personal Access Tokens

Personal Access Tokens (PATs) sind langlebige Anmeldedaten für programmatischen Zugriff.

Erstellen Sie ein PAT

Über Benutzeroberfläche:

Schritt 1: Navigieren Sie zu Einstellungen

Klicken Sie auf Ihr Profilsymbol → Einstellungen

Schritt 2: Gehen Sie zu API-Schlüssel

Klicken Sie auf "API-Schlüssel" in der linken Seitenleiste

Schritt 3: Klicken Sie auf "Token erstellen"

Klicken Sie auf die "+ Neues Personal Access Token" Schaltfläche

Schritt 4: Token konfigurieren

  • Name (Erforderlich)
    • Aussagekräftiger Name für diesen Token
    • Beispiele: "CI/CD Pipeline", "Automation Scripts", "Production Bot"
  • Ablauf (Optional)
    • Standard: Kein Ablauf
    • Optionen: 30 Tage, 90 Tage, 1 Jahr, benutzerdefiniert, nie
    • Empfehlung: Ablauf zur Sicherheit einstellen
  • Scopes (Kommt bald)
    • Derzeit: Vollständiger Zugriff
    • Zukunft: Granulare Berechtigungen (agents:read, tasks:write, etc.)

Schritt 5: Token kopieren

⚠️ WICHTIG: Token wird nur einmal angezeigt!

td_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
  • Kopieren Sie sofort und speichern Sie sicher
  • Wenn verloren, müssen Sie Token widerrufen und einen neuen erstellen
  • Commiten Sie niemals zu Git und teilen Sie nicht öffentlich

Schritt 6: Token sicher speichern

Speichern Sie in einem Passwort-Manager oder einer sicheren Umgebungsvariable:

# .bashrc oder .zshrc
export TEAMDAY_API_TOKEN="td_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

PATs verwenden

Mit CLI:

# Methode 1: Set über Befehl
teamday auth set-key "td_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

# Methode 2: Umgebungsvariable
export TEAMDAY_API_TOKEN="td_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
teamday agents list

# Methode 3: Inline
TEAMDAY_API_TOKEN="td_xxx" teamday agents list

Mit API:

curl -X GET https://cc.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer td_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Mit JavaScript:

const TEAMDAY_TOKEN = process.env.TEAMDAY_API_TOKEN;

const response = await fetch('https://cc.teamday.ai/api/v1/agents', {
  headers: {
    'Authorization': `Bearer ${TEAMDAY_TOKEN}`,
    'Content-Type': 'application/json'
  }
});

const agents = await response.json();

Mit Python:

import os
import requests

TEAMDAY_TOKEN = os.environ['TEAMDAY_API_TOKEN']

response = requests.get(
    'https://cc.teamday.ai/api/v1/agents',
    headers={
        'Authorization': f'Bearer {TEAMDAY_TOKEN}',
        'Content-Type': 'application/json'
    }
)

agents = response.json()

PATs verwalten

Aktive Tokens anzeigen:

Über Benutzeroberfläche:

  1. Einstellungen → API-Schlüssel
  2. Siehe Liste der aktiven Tokens mit:
    • Name
    • Erstellungsdatum
    • Letztes Verwendungsdatum
    • Ablauf (falls gesetzt)

Tokens sind gehashed - Sie können den Token-Wert nach der Erstellung nicht anzeigen.

Über CLI:

teamday auth tokens list

Ausgabe:

ID          Name                    Created      Last Used    Expires
---------------------------------------------------------------------------
token_123   CI/CD Pipeline          2024-12-01   2025-01-15   2025-06-01
token_456   Production Bot          2024-10-15   2025-01-14   Never
token_789   Local Development       2025-01-10   2025-01-15   2025-02-10

PATs widerrufen

Über Benutzeroberfläche:

  1. Einstellungen → API-Schlüssel
  2. Suchen Sie den Token in der Liste
  3. Klicken Sie auf "⋯" → "Widerrufen"
  4. Bestätigen Sie

Über CLI:

teamday auth tokens revoke token_123

Auswirkung:

  • Token funktioniert sofort nicht mehr
  • Alle Anfragen mit diesem Token geben 401 Unauthorized zurück
  • Kann nicht rückgängig gemacht werden - müssen neuen Token erstellen

Wann zu widerrufen:

  • Token möglicherweise kompromittiert
  • Mitarbeiter verlässt Team
  • Wechsel zu neuem Token
  • Token wird nicht mehr benötigt

Token-Rotation

Best Practice: Tokens regelmäßig rotieren

Strategie:

  1. Neuen Token erstellen
  2. Systeme aktualisieren, um neuen Token zu verwenden
  3. Überprüfen Sie, ob der neue Token funktioniert
  4. Alten Token widerrufen

Beispiel-Skript:

#!/bin/bash
# rotate-token.sh

# Erstelle neuen Token (via UI, Wert kopieren)
NEW_TOKEN="td_new_token_here"

# Update in CI/CD (Beispiel: GitHub Actions)
gh secret set TEAMDAY_API_TOKEN --body "$NEW_TOKEN"

# Update in Produktionsumgebung
kubectl create secret generic teamday-token \
  --from-literal=token="$NEW_TOKEN" \
  --dry-run=client -o yaml | kubectl apply -f -

# Test neuer Token
TEAMDAY_API_TOKEN="$NEW_TOKEN" teamday agents list

# Falls erfolgreich, alten Token widerrufen
teamday auth tokens revoke token_old_id

OAuth für CLI

OAuth bietet sicheren, kurzlebigen Zugriff für CLI-Benutzer.

So funktioniert OAuth

sequenceDiagram
    participant CLI
    participant Browser
    participant TeamDay

    CLI->>TeamDay: 1. Authentifizierung initiieren
    TeamDay->>CLI: 2. Authentifizierungscode + URL zurückgeben
    CLI->>Browser: 3. Authentifizierungs-URL öffnen
    Browser->>TeamDay: 4. Benutzer meldet sich an
    TeamDay->>Browser: 5. Autorisierung erfolgreich
    CLI->>TeamDay: 6. Tokens abfragen
    TeamDay->>CLI: 7. Access + Refresh Tokens zurückgeben
    CLI->>TeamDay: 8. API-Anfragen stellen
    Note over CLI,TeamDay: Access Token läuft in 15 min ab
    CLI->>TeamDay: 9. Token aktualisieren
    TeamDay->>CLI: 10. Neuer Access Token

Mit OAuth anmelden

Schritt 1: Führen Sie Login-Befehl aus

teamday auth login

Schritt 2: CLI initiiert Authentifizierung

Authentifizierung wird eingeleitet...

Bitte öffnen Sie diese URL in Ihrem Browser:
https://cc.teamday.ai/cli-auth?code=abc123xyz

Warten auf Autorisierung...

Schritt 3: Browser wird automatisch geöffnet

  • Falls Browser nicht öffnet, kopieren/einfügen Sie URL manuell
  • Sie sehen die TeamDay-Anmeldeseite

Schritt 4: Melden Sie sich bei TeamDay an

  • Geben Sie E-Mail/Passwort ein
  • Oder verwenden Sie OAuth-Provider (Google, GitHub)

Schritt 5: Autorisieren Sie CLI

Seite anzeigen:

Autorisieren Sie TeamDay CLI

Die TeamDay CLI fordert Zugriff auf Ihren Account an.

Dies ermöglicht:
✓ Agenten verwalten
✓ Agenten ausführen
✓ Auf Spaces zugreifen
✓ Aufgaben erstellen

[Autorisieren] [Abbrechen]

Klicken Sie auf "Autorisieren"

Schritt 6: Erfolg

Browser anzeigen:

✓ Autorisierung erfolgreich!

Sie können dieses Fenster schließen und zu Ihrem Terminal zurückkehren.

CLI anzeigen:

✓ Authentifizierung erfolgreich!

Sie sind angemeldet als: [email protected]
Organisation: Acme Corp

Token-Speicherung

OAuth Tokens lokal gespeichert:

Standort:

  • macOS: ~/.teamday/config.json
  • Linux: ~/.teamday/config.json
  • Windows: %USERPROFILE%\.teamday\config.json

Inhalte:

{
  "accessToken": "ey...",
  "refreshToken": "ey...",
  "expiresAt": "2025-01-15T11:00:00Z",
  "user": {
    "email": "[email protected]",
    "organizationId": "org_abc123"
  }
}

Sicherheit:

  • Datei hat strikte Berechtigungen (600 auf Unix)
  • Tokens sind in Ruhe verschlüsselt (auf einigen Systemen)
  • Automatisch aktualisiert vor Ablauf

Automatische Token-Aktualisierung

CLI aktualisiert automatisch Access Tokens:

# Erster Befehl: Token gültig
teamday agents list
# Funktioniert sofort

# ... 15 Minuten später, Token abgelaufen ...

# Nächster Befehl: Token automatisch aktualisiert
teamday agents exec char_123 "message"
# CLI erkennt Ablauf, aktualisiert Token, führt dann aus

Manuelle Aktualisierung:

teamday auth refresh

Authentifizierungsstatus überprüfen

teamday auth status

Ausgabe:

✓ Authentifiziert

Benutzer: [email protected]
Organisation: Acme Corp
Methode: OAuth
Access Token: Gültig (läuft in 12 min ab)
Refresh Token: Gültig (läuft in 85 Tagen ab)

Abmelden

teamday auth logout

Dies:

  • Löscht lokale Tokens
  • Widerruft Access Token auf dem Server
  • Erfordert Neu-Authentifizierung für nächsten Befehl

Sicherheit Best Practices

1. Commiten Sie niemals Tokens zu Git

Verwenden Sie .gitignore:

# .gitignore
.env
.env.local
.teamday/
config.json
*_token.txt

Überprüfen Sie vor dem Commit:

git diff --cached | grep -i "td_"

2. Verwenden Sie Umgebungsvariablen

Für PATs:

# .env (NICHT COMMITEN)
TEAMDAY_API_TOKEN=td_xxx

# Laden Sie in Skripten
export $(cat .env | xargs)

In CI/CD:

  • GitHub Actions: Repository Secrets
  • GitLab CI: CI/CD Variables
  • CircleCI: Project Settings → Environment Variables

3. Prinzip der minimalen Berechtigung

Erstellen Sie separate Tokens für verschiedene Zwecke:

✓ Gut:
- "CI/CD Deploy" - Nur in Deployment Pipeline verwendet
- "Daily Reports" - Nur für automatisierte Berichterstattung verwendet
- "Development" - Lokal verwendet, häufig rotiert

✗ Schlecht:
- "Master Token" - Überall verwendet (falls kompromittiert, vollständiger Zugriff)

4. Ablaufdaten einstellen

Für Automatisierungs-Tokens:

Kurzfristige Projekte: 30 Tage
Langfristige CI/CD: 90 Tage
Vierteljährliche Überprüfung: 1 Jahr

Überprüfen Sie vor Ablauf:

  • Kalendererinnerungen einstellen
  • Ablauf-Benachrichtigungen automatisieren
  • Proaktiv rotieren

5. Token-Nutzung überwachen

Über Benutzeroberfläche: Einstellungen → API-Schlüssel → Sehen Sie "Last Used"

Rote Flaggen:

  • Tokens, die nie verwendet werden (löschen)
  • Unerwartete Verwendungszeiten (untersuchen)
  • Hohes Request-Volumen (potentieller Missbrauch)

6. Sichere Token-Speicherung

Lokale Entwicklung:

# Verwenden Sie einen Passwort-Manager
# Beispiel: 1Password, LastPass, Bitwarden

# Oder verschlüsselte Datei
gpg --encrypt --recipient [email protected] token.txt
# Entschlüsseln, wenn nötig
gpg --decrypt token.txt.gpg

Produktion:

# Verwenden Sie Secret Management
# AWS: Secrets Manager
# GCP: Secret Manager
# Azure: Key Vault
# Kubernetes: Secrets

7. Regelmäßig rotieren

Empfohlener Zeitplan:

  • Entwicklungs-Tokens: Monatlich
  • CI/CD-Tokens: Vierteljährlich
  • Produktions-Tokens: Alle 6 Monate
  • Bei Team-Änderungen: Sofort

8. Zugriff auditieren

Monatliche Überprüfung:

# Alle Tokens auflisten
teamday auth tokens list

# Überprüfen Sie jedes:
# - Wird noch benötigt?
# - Besitzer noch im Team?
# - Kürzlich verwendet?
# - Ablauf angemessen?

# Unnötige Tokens widerrufen
teamday auth tokens revoke token_old_id

9. Incident Response

Falls Token kompromittiert:

Schritt 1: Sofort widerrufen

teamday auth tokens revoke token_compromised_id

Schritt 2: Überprüfen Sie Audit-Logs

teamday audit --token token_compromised_id --since "1 week ago"

Schritt 3: Schaden beurteilen

  • Auf welche Agenten wurde zugegriffen?
  • Welche Daten wurden freigelegt?
  • Wurden destruktive Aktionen durchgeführt?

Schritt 4: Alle Tokens rotieren

  • Wissen nicht, welcher kompromittiert ist? Alle rotieren

Schritt 5: Dokumentation aktualisieren

  • Wie wurde es kompromittiert?
  • Wie zu verhindern in der Zukunft?

10. Rate Limiting

Seien Sie sich Rate-Limits bewusst:

  • Mit PAT: 1000 Anfragen/Stunde
  • Mit OAuth: 500 Anfragen/Stunde

Vermeiden Sie:

# Schlecht: Polling in enger Schleife
while true; do
  teamday agents list
  sleep 1
done

Tun Sie:

# Gut: Angemessenes Polling
while true; do
  teamday agents list
  sleep 60  # Überprüfen alle Minute
done

Fehlerbehebung

Ungültige Token-Fehler

Symptome:

Error: Invalid token or token expired
Status: 401 Unauthorized

Lösungen:

Für PAT:

# Überprüfen Sie, dass der Token korrekt ist
echo $TEAMDAY_API_TOKEN

# Überprüfen Sie, ob Token aktiv ist
teamday auth tokens list

# Erstelle neuen Token, falls nötig
# (via UI: Einstellungen → API-Schlüssel → Neuer Token)

Für OAuth:

# Token abgelaufen, aktualisieren
teamday auth refresh

# Oder erneut anmelden
teamday auth logout
teamday auth login

Berechtigung verweigert

Symptome:

Error: You do not have permission to perform this action
Status: 403 Forbidden

Ursachen:

  • Token hat unzureichende Scopes (zukünftige Funktion)
  • Benutzerrolle erlaubt keine Aktion
  • Ressource gehört zu anderer Organisation

Lösungen:

# Überprüfen Sie Auth-Status
teamday auth status

# Überprüfen Sie Organisation
teamday config get organization

# Organisation wechseln (falls Mitglied mehrerer)
teamday config set organization org_different_id

Token nicht gefunden

Symptome:

Error: No authentication token found

Lösungen:

# Überprüfen Sie, ob angemeldet
teamday auth status

# Falls nicht, anmelden
teamday auth login

# Oder PAT setzen
teamday auth set-key "td_xxx"

# Oder Umgebungsvariable verwenden
export TEAMDAY_API_TOKEN="td_xxx"

OAuth Flow hängt

Symptome: Browser zeigt nie Erfolgsseite

Lösungen:

1. Überprüfen Sie Browser-Konsole auf Fehler

2. Manuelle Fertigstellung:

# Hängenden Flow abbrechen
Ctrl+C

# Versuchen Sie erneut mit manueller Code-Eingabe
teamday auth login --manual

3. Verwenden Sie stattdessen PAT:

# PAT über UI generieren
# Dann in CLI setzen
teamday auth set-key "td_xxx"

Rate-Limit überschritten

Symptome:

Error: Rate limit exceeded
Status: 429 Too Many Requests
Retry-After: 3600

Lösungen:

# Warten Sie auf Rate-Limit-Reset (1 Stunde)

# Oder implementieren Sie exponentielles Backoff
#!/bin/bash
retry=0
max_retries=5
while [ $retry -lt $max_retries ]; do
  if teamday agents list; then
    exit 0
  fi
  wait=$((2 ** retry))
  echo "Retry in ${wait}s..."
  sleep $wait
  retry=$((retry + 1))
done

Nächste Schritte