Authentifizierung

Jeder geschützte Endpunkt benötigt ein Bearer-Token im Authorization-Header. Zwei Token-Arten werden akzeptiert — ein Firebase-ID-Token oder ein xingen-API-Key.

Bearer-Token

Authorization: Bearer xgn_live_ihr_schluessel_hier

Firebase-ID-Token — wird beim Login im xingen-Dashboard ausgestellt. Gedacht für interaktive Sessions im Browser, nicht für langlebige Integrationen.
API-Key — mit Präfix xgn_live_ (Produktion) oder xgn_test_ (Sandbox). Gedacht für Server-zu-Server- und CI/CD-Integrationen.

API-Key erstellen

Registrieren Sie sich und gehen Sie zu Einstellungen → API-Keys, um einen Schlüssel zu erstellen — das funktioniert bereits im kostenlosen Plan, kein Upgrade nötig. Der Klartext-Schlüssel wird einmalig angezeigt; bewahren Sie ihn sicher auf, er kann nicht erneut abgerufen werden.

Alternativ können Sie Schlüssel direkt über die API erstellen:

POST /v1/api-keys
Content-Type: application/json

{
  "name": "Production CI",
  "sandbox": false,
  "quotaLimit": null
}

quotaLimit ist optional. Im kostenlosen Plan wird sie serverseitig auf 500 Anfragen/Monat begrenzt — unabhängig davon, was Sie anfordern; null oder ein höherer Wert wird automatisch auf 500 gekappt. Pro-Konten können ein eigenes Limit angeben oder es für kein Limit auf null belassen (Fair-Use-Richtlinie gilt).

Sandbox- vs. Live-Keys

xgn_test_-Keys laufen im Sandbox-Modus:

Jede Anfrage liefert ein festes, fest codiertes validated-Ergebnis — es findet keine echte Validierung statt, unabhängig vom hochgeladenen Inhalt. Nutzen Sie Sandbox-Ergebnisse nicht für geschäftliche Entscheidungen.
Sandbox-Anfragen zählen nie gegen Ihr Kontingent.

xgn_live_-Keys führen echte, asynchrone Validierung durch und zählen gegen Ihr monatliches Kontingent.

Zugriffsumfang eines Keys

xingen hat noch kein Scope-/Berechtigungssystem — ein API-Key hat denselben Zugriff wie Ihr Konto: Er kann Ihre eigenen Rechnungen einreichen und abrufen sowie Ihre eigenen API-Keys verwalten. Es gibt derzeit keine Möglichkeit, einen Schlüssel auf eine Teilmenge davon zu beschränken (z. B. nur lesend oder nur validierend).

Planabhängige Validierungsprofile

EN16931 und PEPPOL stehen in jedem Plan zur Verfügung. XRECHNUNG, FRANCE und ITALY erfordern ein Pro-Abo — das Upgrade ist kostenlos und sofort wirksam, unter Einstellungen. Eine Anfrage mit einem dieser Profile von einem kostenlosen Konto wird mit 403 Forbidden abgelehnt.

Schlüssel rotieren

Für eine Rotation ohne Ausfallzeit:

Neuen Schlüssel erstellen — er ist sofort aktiv
Umgebungsvariable / Secret Manager aktualisieren
Alten Schlüssel widerrufen, sobald alle Deployments den neuen Wert verwenden

Beide Schlüssel funktionieren während der Übergangsphase gleichzeitig. Nach dem Widerruf gibt es keine Übergangsfrist — ein widerrufener Schlüssel funktioniert ab der nächsten Anfrage nicht mehr.

Fehler

Fehlende oder ungültige Anmeldedaten liefern 401 Unauthorized:

{
  "message": "Unauthorized access of protected resource, invalid credentials",
  "error": "UNAUTHORIZED",
  "code": 401,
  "timestamp": "2024-03-01T10:00:00.000+00:00"
}

Überschreiten des Kontingents liefert 429 Too Many Requests:

{
  "error": "Quota exceeded"
}

Siehe die Fehler-Referenz für Validierungs-Fehlercodes.