Authentifizierung

Alle Routen der API, abgesehen von einigen öffentlichen Routen (status, ping, pricing, auth/login, auth/demo), verlangen ein Bearer-Token im Header Authorization.

GET /v1/auth/me HTTP/1.1
Host: api.novafisko.com
Authorization: Bearer 57|n8Yw2c0vXk4JrPq1LmZs
Accept: application/json

NovaFisko unterscheidet zwei Arten von Tokens.

In beiden Fällen handelt das Token im Namen eines Benutzers: Es sieht die Kanzleien und Mandate, auf die dieser Benutzer Zugriff hat, nicht mehr und nicht weniger. Ein nicht zugängliches Mandat antwortet mit 404, niemals mit 403, um seine Existenz nicht preiszugeben.

Sitzungstoken#

Anmelden#

curl -X POST https://api.novafisko.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "claire.dumont@fiduciaire-exemple.be",
    "password": "votre-mot-de-passe",
    "device_name": "script-export-mensuel"
  }'

Antwort 201:

{
  "token": "57|n8Yw2c0vXk4JrPq1LmZs",
  "user": {
    "id": 12,
    "name": "Claire Dumont",
    "email": "claire.dumont@fiduciaire-exemple.be",
    "locale": "fr",
    "is_platform_admin": false,
    "firms": [
      {"public_token": "Fd7hQ2mN8sXa", "name": "Fiduciaire Exemple", "role": "admin"}
    ],
    "managed_firms": [
      {"public_token": "Fd7hQ2mN8sXa", "name": "Fiduciaire Exemple"}
    ]
  }
}

Falsche Zugangsdaten führen zu 422 mit einem Fehler im Feld email. Die Route ist auf 20 Requests pro Minute und IP-Adresse begrenzt. Nach 10 Fehlversuchen wird jeder weitere Versuch 5 Minuten lang abgelehnt.

Den aktuellen Benutzer abfragen#

GET /v1/auth/me liefert dasselbe Objekt user wie die Anmeldung, ergänzt um is_demo (true für einen Benutzer der Demo-Kanzlei). Dieser Aufruf eignet sich ideal, um zu prüfen, ob ein Token noch gültig ist.

Abmelden#

POST /v1/auth/logout widerruft das für den Aufruf verwendete Token und antwortet mit 204 ohne Body.

Integrationstokens#

Ein Integrationstoken ist dafür gedacht, einer anderen Lösung anvertraut zu werden. Es trägt einen Namen, eine Liste von Berechtigungen, ein optionales Ablaufdatum und das Datum seiner letzten Verwendung.

Berechtigungen#

Die sechs Routen der Offline-Synchronisierung verlangen nur sync. Ein Konnektor, der lediglich die Änderungen mit sync/pull verfolgt, benötigt daher weder read noch write. Die Route POST companies/{company}/sync/novadesko, die den Import aus Novadesko erneut anstößt, gehört nicht dazu: Sie fällt unter write.

Ein Token erstellen#

Die Erstellung erfordert ein Sitzungstoken: Ein Integrationstoken kann keine weiteren Tokens erstellen.

curl -X POST https://api.novafisko.com/v1/auth/tokens \
  -H "Authorization: Bearer 57|n8Yw2c0vXk4JrPq1LmZs" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Connecteur ERP Atelier",
    "abilities": ["read", "write"],
    "expires_in_days": 365
  }'

Antwort 201:

{
  "token": "83|4Hq7ZtVb2Mx9KcLp0RsWyE1uNaJd6FgT",
  "integration_token": {
    "id": 83,
    "name": "Connecteur ERP Atelier",
    "abilities": ["read", "write"],
    "created_at": "2026-10-05T08:30:11+00:00",
    "expires_at": "2027-10-05T08:30:11+00:00",
    "last_used_at": null
  }
}

Ein Benutzer kann höchstens 50 Integrationstokens besitzen. Darüber hinaus antwortet die Erstellung mit 422 und dem Code token_limit_reached. Die Route ist auf 20 Erstellungen pro Minute begrenzt.

Tokens auflisten#

curl https://api.novafisko.com/v1/auth/tokens \
  -H "Authorization: Bearer 57|n8Yw2c0vXk4JrPq1LmZs"

{
  "data": [
    {
      "id": 83,
      "name": "Connecteur ERP Atelier",
      "abilities": ["read", "write"],
      "created_at": "2026-10-05T08:30:11+00:00",
      "expires_at": "2027-10-05T08:30:11+00:00",
      "last_used_at": "2026-10-05T09:02:47+00:00"
    }
  ]
}

Es werden nur Ihre eigenen Integrationstokens aufgelistet. Die Sitzungstokens der Anwendungen erscheinen dort nicht.

Ein Token widerrufen#

curl -X DELETE https://api.novafisko.com/v1/auth/tokens/83 \
  -H "Authorization: Bearer 57|n8Yw2c0vXk4JrPq1LmZs"

Die Antwort ist 204. Das Token funktioniert ab sofort nicht mehr. Eine unbekannte Kennung oder eine, die nicht zu einem Ihrer Integrationstokens gehört, antwortet mit 404.

Authentifizierungsfehler#

Beispiel einer Ablehnung wegen fehlender Berechtigung:

{
  "message": "Ce jeton n'a pas la capacité requise pour cette action.",
  "code": "token_ability_missing",
  "required_ability": "write"
}

Bewährte Vorgehensweisen#

• Ein Token pro Integration. So können Sie eines widerrufen, ohne die anderen zu unterbrechen, und die Spalte der letzten Verwendung bleibt aussagekräftig.
• So wenige Berechtigungen wie möglich. Ein Reporting-Werkzeug benötigt nur read.
• Ein Ablaufdatum. Legen Sie expires_in_days fest und planen Sie die Erneuerung vor dem Stichtag.
• Ein eigener Benutzer. Legen Sie in der Kanzlei einen Mitarbeiter an, der der Integration vorbehalten ist, mit der unbedingt nötigen Rolle. Der Verlauf zeigt dann klar, was die Integration getan hat.
• Verschlüsselte Aufbewahrung. Bewahren Sie das Token in einem Secret-Manager oder einer Umgebungsvariablen auf, niemals im Quellcode, in einem Git-Repository oder in einer Anwendung, die im Browser Ihrer Kunden läuft.
• Nur HTTPS. Senden Sie das Token niemals über eine unverschlüsselte Verbindung und setzen Sie es nicht in eine URL.

Siehe auch#

• Überblick über die API
• Konventionen
• Fehler und Limits
• Rollen und Team