Authentifizierung

Alle fiskaly-APIs verwenden JWT-basierte Authentifizierung. Dieser Guide behandelt die verschiedenen Authentifizierungsmuster über alle Produkte hinweg.

Authentifizierungsablauf

API Key + Secret  →  POST /auth (or /tokens)  →  access_token + refresh_token
                                                       │
                                                       ├─ Im Authorization-Header verwenden
                                                       │
                                                       └─ Bei 401 → erneuern oder erneut authentifizieren

SIGN DE, SIGN AT, DSFINVK DE, RECEIPT

Diese Produkte verwenden einen unkomplizierten Auth-Endpunkt:

curl -X POST https://kassensichv-middleware.fiskaly.com/api/v2/auth \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "api_secret": "YOUR_API_SECRET"
  }'

const response = await fetch(
  "https://kassensichv-middleware.fiskaly.com/api/v2/auth",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      api_key: "YOUR_API_KEY",
      api_secret: "YOUR_API_SECRET",
    }),
  }
);
const { access_token, refresh_token } = await response.json();

import requests

response = requests.post(
    "https://kassensichv-middleware.fiskaly.com/api/v2/auth",
    json={"api_key": "YOUR_API_KEY", "api_secret": "YOUR_API_SECRET"},
)
tokens = response.json()
access_token = tokens["access_token"]
refresh_token = tokens["refresh_token"]

Antwort

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "access_token_expires_in": 86400,
  "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token_expires_in": 172800
}

Feld	Beschreibung
`access_token`	JWT-Token gültig für 24 Stunden — als `Authorization: Bearer <token>` einfügen
`refresh_token`	Token gültig für 48 Stunden — zum Abrufen eines neuen Access-Tokens verwenden

SIGN ES

SIGN ES umhüllt die Auth-Anfrage in einen content-Envelope:

curl -X POST https://test.es.sign.fiskaly.com/api/v1/auth \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "api_key": "YOUR_API_KEY",
      "api_secret": "YOUR_API_SECRET"
    }
  }'

const response = await fetch(
  "https://test.es.sign.fiskaly.com/api/v1/auth",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      content: {
        api_key: "YOUR_API_KEY",
        api_secret: "YOUR_API_SECRET",
      },
    }),
  }
);
const { access_token } = await response.json();

response = requests.post(
    "https://test.es.sign.fiskaly.com/api/v1/auth",
    json={"content": {"api_key": "YOUR_API_KEY", "api_secret": "YOUR_API_SECRET"}},
)
access_token = response.json()["access_token"]

SIGN IT, SIGN FR, E-Invoice

Diese neueren APIs verwenden /tokens mit dem content.type-Diskriminator und erfordern zusätzliche Header:

curl -X POST https://test.api.fiskaly.com/tokens \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2026-02-03" \
  -d '{
    "content": {
      "type": "API_KEY",
      "key": "YOUR_API_KEY",
      "secret": "YOUR_API_SECRET"
    }
  }'

const response = await fetch(
  "https://test.api.fiskaly.com/tokens",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Version": "2026-02-03",
    },
    body: JSON.stringify({
      content: {
        type: "API_KEY",
        key: "YOUR_API_KEY",
        secret: "YOUR_API_SECRET",
      },
    }),
  }
);
const { access_token } = await response.json();

response = requests.post(
    "https://test.api.fiskaly.com/tokens",
    headers={"X-Api-Version": "2026-02-03"},
    json={"content": {"type": "API_KEY", "key": "YOUR_API_KEY", "secret": "YOUR_API_SECRET"}},
)
access_token = response.json()["access_token"]

Scoped-Authentifizierung

Um Anfragen auf eine bestimmte Organisation UNIT zu beschränken, fügen Sie den X-Scope-Identifier-Header ein:

Authorization: Bearer <access_token>
X-Api-Version: 2026-02-03
X-Scope-Identifier: <organization_unit_id>

Token-Erneuerung

Wenn der Access-Token abläuft, verwenden Sie den Refresh-Token anstatt sich erneut mit Zugangsdaten zu authentifizieren:

curl -X POST https://kassensichv-middleware.fiskaly.com/api/v2/auth \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "YOUR_REFRESH_TOKEN"}'

const response = await fetch(
  "https://kassensichv-middleware.fiskaly.com/api/v2/auth",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ refresh_token: refreshToken }),
  }
);
const { access_token } = await response.json();

response = requests.post(
    "https://kassensichv-middleware.fiskaly.com/api/v2/auth",
    json={"refresh_token": refresh_token},
)
access_token = response.json()["access_token"]

Best Practices

💡Token zwischenspeichern

Access-Tokens sind 24 Stunden gültig. Cachen Sie den Token und erneuern Sie ihn nur bei 401-Antworten. Eine erneute Authentifizierung pro Anfrage verursacht ~100 ms Mehraufwand pro Aufruf.

⚠️Secrets niemals offenlegen

API-Secrets in Umgebungsvariablen oder einem Secret-Manager speichern - Secrets niemals in die Quellcodeverwaltung committen - Secrets niemals in clientseitigem Code einfügen - API Keys rotieren, wenn ein Secret kompromittiert wurde

Empfohlene Token-Strategie

Einmalig beim Start der Anwendung authentifizieren
access_token und refresh_token im Speicher ablegen
Bei 401-Antwort versuchen, mit dem refresh_token zu erneuern
Wenn Erneuerung fehlschlägt (Token abgelaufen), mit API Key + Secret erneut authentifizieren
Wenn erneute Authentifizierung fehlschlägt, den Fehler dem Betreiber anzeigen

Authentifizierung