Authentifizierung & Authorization

MaxiCore unterstützt mehrere Authentifizierungsmethoden: Clerk OAuth, Device-Tokens und Managed Agent Pairing.

Clerk OAuth (Standard für Browser)

Für Web-Apps verwende Clerk OAuth 2.0:

import { useAuth } from '@clerk/clerk-react';

export function ApiClient() {
  const { getToken } = useAuth();

  async function fetchAgents() {
    const token = await getToken({ template: 'maxicore' });
    const response = await fetch('https://api.maxicore.ch/v2/agents', {
      headers: { 'Authorization': `Bearer ${token}` }
    });
    return response.json();
  }
}

Device-Token (CLI & Desktop)

Für lokale Anwendungen und CLI Tools:

1. Device-Pairing initiieren

maxicore auth pair

Dies öffnet einen Browser und zeigt einen Code:

Device Code: DC-ABC123-XYZ789
Verification Code: 12345

Öffne: https://maxicore.ch/pair?code=DC-ABC123-XYZ789

2. Im Browser verifizieren

Der Benutzer gibt den 5-stelligen Code ein und autorisiert die Verbindung.

3. Token speichern

Nach erfolgreicher Verifizierung wird ein Device-Token in ~/.maxicore/token gespeichert:

# Token anschauen
cat ~/.maxicore/token
# Output: mc_token_eyJhbGc...

4. Token verwenden

curl -H "Authorization: Bearer mc_token_eyJhbGc..." \
  https://api.maxicore.ch/v2/agents

Token Lifetime: 30 Tage (automatisch erneuert bei Nutzung)

Managed Agent Pairing (Service-Key)

Für Managed Agents auf Servern:

# Pairing-Key generieren
sudo maxicore agent init

# Output:
# Service Pairing Key: MC-PROD-123456-ABCDEF
# Keep this key secret!

Dieser Key wird im Portal eingegeben und authentifiziert den Agent gegenüber MaxiCore API:

# Agent nutzt Key automatisch
export MAXICORE_SERVICE_KEY="MC-PROD-123456-ABCDEF"
maxicore agent run

Der Agent bekommt einen API Token zurück und speichert ihn lokal in /opt/maxicore/agent/.token.

Authorization & Roles

Jeder Benutzer hat eine Rolle pro Workspace:

Rolle	Agents	Tasks	Settings	Policies
Viewer	Nur anschauen	Logs lesen	Keine	Keine
Editor	Nutzen, ändern	Erstellen, steuern	Begrenzt	Keine
Admin	Voll Kontrolle	Voll Kontrolle	Voll	Alle ändern
Owner	Voll + Löschen	Voll + Löschen	Alles	Alles

Rollen werden im Portal unter Settings → Members pro Workspace verwaltet.

API-Key für Skripte

Für automatisierte Prozesse (CI/CD, Cron Jobs):

# Genrate API-Key
maxicore auth create-api-key --name "CI/CD Pipeline" --expires 90

# Output:
# API Key: sk-abc123...
# Save this securely!

Verwende ihn wie einen Device-Token:

export MAXICORE_API_KEY="sk-abc123..."
curl -H "Authorization: Bearer $MAXICORE_API_KEY" \
  https://api.maxicore.ch/v2/agents

Rotation: API-Keys sollten monatlich rotiert werden. Alte Keys unter Settings → API Keys deaktivieren.

Token Security

Wo speichern?

• CLI: ~/.maxicore/token (File-Permissions 600)
• Browser: Session-Cookie (HttpOnly, Secure)
• CI/CD: GitHub Secret oder Vault
• NIEMALS: In Git, Logs, oder Umgebungsvariablen in Code

Revoke/Logout

# Aktuellen Token revoken
maxicore auth revoke

# Device-Pairing löschen
maxicore auth unpair

Nach Revoke muss neu gepairt werden.

Refresh & Expiration

• Clerk Token: Automatisch erneuert (kurz vor Expiration)
• Device-Token: 30 Tage Lifetime (automatisch erneuert bei Nutzung)
• API-Key: Statisch, kein Refresh (Expiration nach Konfiguration)

Token-Status überprüfen:

maxicore auth status
# Output: Token expires in 23 days

Troubleshooting

"Unauthorized" 401 Error:

# Token regenerieren
maxicore auth pair

Device-Code abgelaufen: Codes sind 15 Minuten gültig. Starte neu:

maxicore auth pair

API-Key ungültig: Überprüfe unter Settings → API Keys ob der Key aktiv ist.