API-Schlüssel

API-Schlüssel sind Authentifizierungstoken, die den Zugriff auf Almirant über externe Tools, Skripte oder programmatische Integrationen ermöglichen. Sie sind der zentrale Mechanismus, um MCP-Clients wie Claude Code, CI/CD-Automatisierungen oder jeden Dienst zu verbinden, der mit der Almirant-API interagieren muss.

Wofür sie verwendet werden

API-Schlüssel werden hauptsächlich verwendet, um:

• Claude Code zu verbinden -- Den MCP-Server von Almirant zu authentifizieren, damit Claude Code Projekte, Boards und Work Items verwalten kann. Weitere Details findest du im Leitfaden zur MCP-Authentifizierung.
• Automatisierungen -- Skripte oder CI/CD-Pipelines, die Work Items erstellen, Status aktualisieren oder KI-Sitzungen erfassen.
• Individuelle Integrationen -- Eigene Anwendungen, die mit der Almirant-API interagieren.

Einen API-Schlüssel erstellen

1. Gehe zu Einstellungen > API-Schlüssel.
2. Klicke auf Neuen API-Schlüssel erstellen.
3. Gib einen deskriptiven Namen ein, um den Zweck des Schlüssels zu identifizieren (zum Beispiel: "Claude Code - Arbeitslaptop", "CI/CD Pipeline", "Interner Bot").
4. Wähle die Berechtigungen aus, die der Schlüssel haben soll.
5. Klicke auf Erstellen.
6. Kopiere den API-Schlüssel sofort.

Den Schlüssel jetzt kopieren

Der vollständige API-Schlüssel wird beim Erstellen nur einmal angezeigt. Wenn du den Dialog schließt, ohne ihn zu kopieren, kannst du ihn nicht wiederherstellen und musst einen neuen erstellen.

Den API-Schlüssel verwenden

API-Schlüssel werden im Header Authorization mit dem Schema Bearer gesendet:

curl -H "Authorization: Bearer tu-api-key-aqui" \
  https://api.almirant.ai/api/projects

Konfiguration für MCP (Claude Code)

Um den API-Schlüssel mit dem Almirant-MCP-Server in Claude Code zu verwenden, füge die folgende Konfiguration zur Datei .mcp.json deines Projekts hinzu:

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp?projectId=uuid-del-proyecto",
      "headers": {
        "Authorization": "Bearer tu-api-key-aqui"
      }
    }
  }
}

Ersetze für die lokale Entwicklung die URL durch http://localhost:3001/mcp?projectId=uuid-del-proyecto.

In der vollständigen Referenz findest du weitere Konfigurationsoptionen für MCP-Authentifizierung und Projektbereich.

API-Schlüssel verwalten

Vorhandene Schlüssel anzeigen

Unter Einstellungen > API-Schlüssel kannst du die Liste aller erstellten Schlüssel mit folgenden Informationen anzeigen:

Feld	Beschreibung
Name	Beim Erstellen des Schlüssels vergebener beschreibender Name
Präfix	Erste Zeichen des Schlüssels zur Identifikation (der Rest ist ausgeblendet)
Erstellungsdatum	Zeitpunkt, zu dem der Schlüssel erstellt wurde
Letzte Verwendung	Datum der letzten mit diesem Schlüssel authentifizierten Anfrage

Einen API-Schlüssel widerrufen

Wenn ein API-Schlüssel kompromittiert ist oder nicht mehr benötigt wird:

1. Gehe zu Einstellungen > API-Schlüssel.
2. Suche den Schlüssel in der Liste.
3. Klicke auf Revocar.
4. Bestätige den Widerruf.

Gefahr

Das Widerrufen eines API-Schlüssels ist sofort wirksam und unumkehrbar. Jeder Dienst oder jedes Tool, das diesen Schlüssel verwendet, funktioniert unverzüglich nicht mehr. Stelle sicher, dass du die Konfigurationen der betroffenen Dienste aktualisierst, bevor du den Schlüssel widerrufst.

Bewährte Sicherheitspraktiken

Sicherheit von API-Schlüsseln

API-Schlüssel ermöglichen den Zugriff auf die Daten deiner Organisation. Behandle sie mit derselben Sorgfalt wie ein Passwort.

• Ein Schlüssel pro Dienst -- Erstelle für jedes Tool oder jeden Dienst einen anderen API-Schlüssel. Wenn einer kompromittiert wird, kannst du ihn widerrufen, ohne die anderen zu beeinträchtigen.
• Beschreibende Namen -- Verwende Namen, die klar angeben, wo der Schlüssel eingesetzt wird: "Claude Code - Büro-PC", "GitHub Actions - Bereitstellung", "Slack-Bot - Benachrichtigungen".
• Schlüssel nicht teilen -- Jedes Teammitglied, das MCP-Zugriff benötigt, sollte einen eigenen API-Schlüssel erstellen.
• Schlüssel nicht im Code speichern -- Committe niemals API-Schlüssel in Code-Repositories. Verwende Umgebungsvariablen oder Secret-Manager.
• Regelmäßig prüfen -- Widerrufe Schlüssel, die nicht mehr verwendet werden oder deren Zweck dir unbekannt ist.
• Kompromittierte Schlüssel rotieren -- Wenn du vermutest, dass ein Schlüssel offengelegt wurde, widerrufe ihn sofort und erstelle einen neuen.

Beispiel für eine sichere Verwendung mit Umgebungsvariablen

Statt den Schlüssel direkt in Konfigurationsdateien zu schreiben:

# .env (excluido de git via .gitignore)
ALMIRANT_API_KEY=tu-api-key-aqui

// .mcp.json (usa referencia a variable de entorno si tu herramienta lo soporta)
{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${ALMIRANT_API_KEY}"
      }
    }
  }
}

Für Entwickler

Authentifizierungsarchitektur

API-Schlüssel werden gehasht in der Tabelle apiKeys des Datenbankschemas gespeichert. Der Authentifizierungsablauf ist:

1. Der Client sendet den API-Schlüssel im Header Authorization: Bearer <key>.
2. Das Backend sucht den gehashten Schlüssel in der Tabelle apiKeys.
3. Wenn der Schlüssel gültig ist, werden der zugehörige Benutzer und die Organisation abgerufen.
4. Der Authentifizierungskontext ({ user, organizationId }) wird in die Anfrage injiziert.
5. Geschützte Routen verwenden diesen Kontext, um Daten nach Organisation zu filtern.

Relevante Endpunkte

Methode	Route	Beschreibung
GET	/api/api-keys	Listet die API-Schlüssel der Organisation auf
POST	/api/api-keys	Erstellt einen neuen API-Schlüssel
DELETE	/api/api-keys/:id	Widerruft einen API-Schlüssel

Berechtigungen und Scopes

API-Schlüssel übernehmen die Berechtigungen des Benutzers, der sie erstellt hat. Der Umfang des Schlüssels ist auf die Organisation des Benutzers beschränkt.