Authenticatie

Alle routes van de API, op enkele publieke routes na (status, ping, pricing, auth/login, auth/demo), vereisen een bearer-token in de header Authorization.

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

NovaFisko onderscheidt twee soorten tokens.

In beide gevallen handelt het token in naam van een gebruiker: het ziet de kantoren en dossiers waartoe die gebruiker toegang heeft, niet meer en niet minder. Een ontoegankelijk dossier antwoordt 404, nooit 403, om het bestaan ervan niet prijs te geven.

Sessietoken#

Aanmelden#

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"
  }'

Antwoord 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"}
    ]
  }
}

Onjuiste inloggegevens geven 422 terug met een fout op het veld email. De route is beperkt tot 20 requests per minuut en per IP-adres. Na 10 mislukte pogingen wordt elke poging gedurende 5 minuten geweigerd.

De huidige gebruiker opvragen#

GET /v1/auth/me geeft hetzelfde object user terug als de aanmelding, aangevuld met is_demo (true voor een gebruiker van het demokantoor). Het is de ideale aanroep om te controleren of een token nog geldig is.

Afmelden#

POST /v1/auth/logout trekt het token in dat voor de aanroep is gebruikt en antwoordt 204 zonder body.

Integratietokens#

Een integratietoken is bedoeld om aan een andere oplossing toe te vertrouwen. Het heeft een naam, een lijst van bevoegdheden, een optionele vervaldatum en de datum van het laatste gebruik.

Bevoegdheden#

De zes routes voor offline synchronisatie vereisen enkel sync. Een connector die alleen de wijzigingen volgt met sync/pull heeft dus noch read noch write nodig. De route POST companies/{company}/sync/novadesko, die de import vanuit Novadesko opnieuw start, hoort daar niet bij: ze valt onder write.

Een token aanmaken#

Voor het aanmaken is een sessietoken vereist: een integratietoken kan geen andere tokens aanmaken.

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
  }'

Antwoord 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
  }
}

Een gebruiker kan maximaal 50 integratietokens bezitten. Daarboven antwoordt het aanmaken 422 met de code token_limit_reached. De route is beperkt tot 20 aanmaken per minuut.

De tokens oplijsten#

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"
    }
  ]
}

Alleen uw eigen integratietokens worden opgelijst. De sessietokens van de applicaties staan er niet in.

Een token intrekken#

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

Het antwoord is 204. Het token werkt onmiddellijk niet meer. Een onbekende id, of een id die niet bij een van uw integratietokens hoort, antwoordt 404.

Authenticatiefouten#

Voorbeeld van een weigering wegens ontbrekende bevoegdheid:

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

Goede praktijken#

• Eén token per integratie. U kunt er één intrekken zonder de andere te onderbreken, en de kolom met het laatste gebruik blijft leesbaar.
• Zo weinig mogelijk bevoegdheden. Een rapporteringstool heeft alleen read nodig.
• Een vervaldatum. Stel expires_in_days in en plan de vernieuwing vóór de vervaldag.
• Een aparte gebruiker. Maak in het kantoor een medewerker aan die voorbehouden is aan de integratie, met de strikt noodzakelijke rol. De geschiedenis toont dan duidelijk wat de integratie heeft gedaan.
• Versleutelde opslag. Bewaar het token in een secrets manager of een omgevingsvariabele, nooit in de broncode, een Git-repository of een applicatie die in de browser van uw klanten draait.
• Alleen HTTPS. Verstuur het token nooit over een onversleutelde verbinding en plaats het niet in een URL.

Zie ook#

• Overzicht van de API
• Conventies
• Fouten en limieten
• Rollen en team