API: auth-and-invites

Ort: work7_laendletech/docs/api/api-auth-and-invites.md

Überblick

• Base-URL / Prefix: /api/auth, /api/invites, /api/admin/access-invite
• Auth: Oeffentliche Endpunkte fuer Registrierung, Passwort- und Verifizierungsfluesse; teilweise eingeladener oder session-basierter Zugriff
• Format: JSON

Endpoint(s)

POST /api/auth/register

Zweck:

Registriert Unternehmen und initialen Benutzer, legt Onboarding-State an und versendet Verifizierungs-E-Mail.

Request

Feld	Typ	Pflicht	Beschreibung
companyName	string	ja	Firmenname
companySlug	string	ja	Firmen-ID / Slug
adminName	string	ja	Name des initialen Benutzers
adminEmail	string	ja	Login-E-Mail
adminPassword	string	ja	Passwort gemaess Passwort-Policy
acceptedTerms	boolean	ja	AGB akzeptiert
acceptedPrivacy	boolean	ja	Datenschutz akzeptiert
inviteToken	string	nein	Einladungstoken, falls Self-Registration deaktiviert ist

Response 200

{
  "success": true,
  "message": "Unternehmen registriert. Prüfen Sie Ihre E-Mail zur Bestätigung.",
  "company": {
    "id": 1,
    "name": "Muster GmbH",
    "company_id": "muster-gmbh"
  },
  "user": {
    "id": 10,
    "email": "admin@example.com",
    "name": "Max Muster"
  }
}

Fehler

HTTP	Bedeutung	Body-Hinweis
400	Validierung / Dublette	error, ggf. details
403	Registrierung nicht erlaubt / Einladung mismatch	error
429	Rate Limit	error, Retry-After Header
500	Serverfehler	error

GET /api/auth/verify-email

Zweck:

Bestaetigt E-Mail-Verifikation ueber Token-Link.

Request

Feld	Typ	Pflicht	Beschreibung
token	query string	ja	Verifikationstoken

Response 200

{
  "success": true
}

Fehler

HTTP	Bedeutung	Body-Hinweis
400	Token fehlt/ungueltig	error
410	Token abgelaufen	error

POST /api/auth/resend-verification

Zweck:

Versendet die Verifikations-E-Mail erneut.

POST /api/auth/forgot-password

Zweck:

Startet den Passwort-Reset-Prozess per E-Mail.

POST /api/auth/reset-password

Zweck:

Setzt ein Passwort mit gueltigem Reset-Token neu.

POST /api/auth/[...nextauth]

Zweck:

Session- und Login-Endpunkt fuer NextAuth Credentials.

GET /api/invites/accept

Zweck:

Prueft oder verarbeitet Einladungsannahme via Link.

POST /api/invites/set-password

Zweck:

Setzt Passwort im Einladungsfluss.

POST /api/admin/access-invite

Zweck:

Erzeugt oder verschickt administrative Einladungen fuer Zugriff.

Rate Limiting / Limits

• Max Requests: Registrierung ist explizit rate-limitiert; weitere Auth-Fluesse sollten ebenfalls als sensibel betrachtet werden
• Timeout: Standard Next.js Route Handler
• Max Payload: JSON-Body, klein bis mittelgross

Breaking Changes / Versionierung

• Kein explizites URL-Versioning; Breaking Changes muessen ueber Dokumentation und UI-Rollout abgestimmt werden.

Beispiel (curl)

curl -sS -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "companyName":"Muster GmbH",
    "companySlug":"muster-gmbh",
    "adminName":"Max Muster",
    "adminEmail":"admin@example.com",
    "adminPassword":"Secret123!",
    "acceptedTerms":true,
    "acceptedPrivacy":true
  }'

Verwandte Notes

• Feature-Spec: work7
• OpenAPI/Schema: /api/swagger

Follow-ups

• [ ] Postman Collection prüfen: passt es in bestehende Collection? Sonst neu anlegen → work7_laendletech/src/postman/ 📅 2026-04-16
• [ ] In Feature-Spec verlinken falls zugehörig 📅 2026-04-16