Authentifizierung - Archyl Docs

Erfahren Sie, wie Sie sich mit der Archyl-API über API-Schlüssel authentifizieren

Authentifizierung

Alle Archyl-API-Anfragen erfordern eine Authentifizierung mit einem API-Schlüssel. Diese Anleitung erklärt, wie Sie API-Schlüssel erstellen und verwenden.

Einen API-Schlüssel Erstellen

  1. Melden Sie sich bei Ihrem Archyl-Konto an
  2. Gehen Sie zu Profil > API-Schlüssel
  3. Klicken Sie auf API-Schlüssel erstellen
  4. Konfigurieren Sie Ihren Schlüssel:
    • Name: Ein beschreibender Name (z.B. "CI/CD-Pipeline", "Lokale Entwicklung")
    • Berechtigungen: Nur Lesen oder Lesen-Schreiben
    • Ablauf: Optionales Ablaufdatum
  5. Klicken Sie auf Erstellen
  6. Kopieren und speichern Sie den Schlüssel sofort - er wird nicht erneut angezeigt

API-Schlüssel-Berechtigungen

Berechtigung Fähigkeiten
Lesen Projekte, Elemente, Dokumentation und Architekturdaten anzeigen
Schreiben Projekte, Elemente und Dokumentation erstellen, ändern und löschen

Wählen Sie die minimalen Berechtigungen, die für Ihren Anwendungsfall erforderlich sind.

Ihren API-Schlüssel Verwenden

Fügen Sie Ihren API-Schlüssel im X-API-Key-Header bei jeder Anfrage ein:

curl -H "X-API-Key: ihr-api-schluessel" \
  https://api.archyl.com/api/v1/projects

Beispiel: Projekte Auflisten

curl -X GET \
  -H "X-API-Key: ihr-api-schluessel" \
  -H "Content-Type: application/json" \
  https://api.archyl.com/api/v1/projects

Beispiel: Ein System Erstellen

curl -X POST \
  -H "X-API-Key: ihr-api-schluessel" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Zahlungsservice",
    "description": "Verarbeitet Zahlungen",
    "type": "internal"
  }' \
  https://api.archyl.com/api/v1/projects/{projectId}/systems

MCP-Server-Authentifizierung

Bei der Verwendung des MCP-Servers mit KI-Assistenten funktioniert die Authentifizierung genauso:

Claude Code / Claude Desktop

Fügen Sie Ihren API-Schlüssel zur MCP-Konfiguration hinzu:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/sse",
      "headers": {
        "X-API-Key": "ihr-api-schluessel"
      }
    }
  }
}

Cursor

In .cursor/mcp.json:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/sse",
      "headers": {
        "X-API-Key": "ihr-api-schluessel"
      }
    }
  }
}

Sicherheits-Best-Practices

Schützen Sie Ihre Schlüssel

  • Committen Sie niemals API-Schlüssel in die Versionskontrolle
  • Verwenden Sie Umgebungsvariablen in CI/CD-Pipelines
  • Rotieren Sie Schlüssel regelmäßig
  • Verwenden Sie separate Schlüssel für verschiedene Umgebungen

Umgebungsvariablen

# In .env speichern (zu .gitignore hinzufügen)
ARCHYL_API_KEY=ihr-api-schluessel

# In Skripten verwenden
curl -H "X-API-Key: $ARCHYL_API_KEY" \
  https://api.archyl.com/api/v1/projects

CI/CD-Integration

Speichern Sie Ihren API-Schlüssel als Secret in Ihrer CI/CD-Plattform:

GitHub Actions:

- name: Architektur Aktualisieren
  env:
    ARCHYL_API_KEY: ${{ secrets.ARCHYL_API_KEY }}
  run: |
    curl -X POST \
      -H "X-API-Key: $ARCHYL_API_KEY" \
      https://api.archyl.com/api/v1/projects/$PROJECT_ID/discover

GitLab CI:

update-architecture:
  script:
    - curl -X POST -H "X-API-Key: $ARCHYL_API_KEY" https://api.archyl.com/api/v1/projects/$PROJECT_ID/discover

API-Schlüssel Verwalten

Schlüssel Anzeigen

Gehen Sie zu Profil > API-Schlüssel, um alle Ihre aktiven Schlüssel zu sehen:

  • Schlüsselname und Erstellungsdatum
  • Berechtigungsstufe
  • Ablaufstatus
  • Letzter Verwendungszeitstempel

Schlüssel Widerrufen

Um einen kompromittierten oder ungenutzten Schlüssel zu widerrufen:

  1. Gehen Sie zu Profil > API-Schlüssel
  2. Finden Sie den zu widerrufenden Schlüssel
  3. Klicken Sie auf Widerrufen
  4. Bestätigen Sie die Aktion

Widerrufene Schlüssel werden sofort ungültig.

Schlüsselablauf

Schlüssel können mit Ablauf konfiguriert werden:

  • Nie: Schlüssel bleibt gültig bis zum manuellen Widerruf
  • 30 Tage: Gut für temporären Zugriff
  • 90 Tage: Ausgewogenheit zwischen Sicherheit und Komfort
  • Benutzerdefiniert: Beliebiges Ablaufdatum festlegen

Fehlerantworten

Ungültiger oder Fehlender Schlüssel

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Ungültiger oder fehlender API-Schlüssel"
  }
}

HTTP-Status: 401 Nicht Autorisiert

Unzureichende Berechtigungen

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API-Schlüssel hat keine Schreibberechtigung"
  }
}

HTTP-Status: 403 Verboten

Abgelaufener Schlüssel

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API-Schlüssel ist abgelaufen"
  }
}

HTTP-Status: 401 Nicht Autorisiert

Nächste Schritte