Zum Hauptinhalt springen

API — Authentifizierung & Sessions

Auth-Methoden​

MethodeWann
Bearer-Token (JWT)Standard für alle API-Calls
OAuth 2.0bei externen Integrationen (z.B. Webapps)
API-Key (Static)für Sub-Systeme / Cron-Jobs
SSO/OIDCEnterprise-Mandanten

Login mit Mail + Passwort​

POST /api/auth/login
{
  "email": "user@example.com",
  "password": "secret"
}

Response:

{
  "accessToken": "eyJ...",
  "refreshToken": "abc...",
  "expiresIn": 3600,
  "user": {
    "id": "uuid",
    "tenantId": "uuid",
    "roles": ["Innendienst"]
  }
}

Token-Refresh​

POST /api/auth/refresh
{
  "refreshToken": "abc..."
}

Refresh-Token-Gültigkeit: 30 Tage. Bei Inaktivität >7 Tage wird empfohlen Re-Login.

Token-Inhalte​

JWT-Payload (decoded):

{
  "sub": "user-uuid",
  "tenant": "tenant-uuid",
  "roles": ["Innendienst"],
  "abilities": ["view:Customer", "create:Workorder"],
  "exp": 1736888400
}

Logout​

POST /api/auth/logout

Invalidiert das aktuelle Refresh-Token (Access-Token läuft natürlich ab).

OAuth 2.0 (für Drittanwendungen)​

  1. Registrierung: Admin → Settings → OAuth-Apps → neue App
  2. Client-ID + Secret generieren
  3. Authorization Code Flow durchführen
  4. Access-Token erhalten

Scope-Beispiele: customers:read, workorders:write, *:read.

API-Key (Server-to-Server)​

Bei Cron-Jobs / Sub-Systemen: statischer API-Key statt User-Token.

POST /api/admin/api-keys
{
  "name": "Banking-Sync-Job",
  "scopes": ["transactions:write", "customers:read"]
}

Response enthält Key — nur einmal sichtbar!

SSO / OIDC​

Bei Enterprise-Mandanten: SSO via Keycloak / Azure AD / Okta.

  • IDP-Konfiguration via Admin → Settings → SSO
  • User wird automatisch erzeugt bei erstem Login (auto-provisioning)
  • Rollen-Mapping per IDP-Group → SpeamCore-Rolle

Sicherheits-Tipps​

  • ❌ API-Token nicht in Git
  • ❌ Token nicht im URL-Parameter (Server-Logs)
  • ✅ Token in Secrets-Manager / Env-Var
  • ✅ Token rotieren (alle 90 Tage)
  • ✅ Bei verdacht auf Leak: sofort revoke

Rate-Limits​

Login: 10 Versuche / 5 min / IP. Bei mehr: 429 + Captcha. Refresh: 100 Versuche / Stunde / Token. Standard-API: siehe Rate-Limits.