Authentification

Toutes les routes de l'API, hormis quelques routes publiques (status, ping, pricing, auth/login, auth/demo), exigent un jeton porteur dans l'en-tête Authorization.

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

NovaFisko distingue deux sortes de jetons.

Dans les deux cas, le jeton agit au nom d'un utilisateur : il voit les cabinets et les dossiers auxquels cet utilisateur a accès, ni plus ni moins. Un dossier inaccessible répond 404, jamais 403, pour ne pas révéler son existence.

Jeton de session#

Se connecter#

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

Réponse 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"}
    ]
  }
}

Des identifiants incorrects renvoient 422 avec une erreur sur le champ email. La route est limitée à 20 requêtes par minute et par adresse IP. Après 10 échecs, toute tentative est refusée pendant 5 minutes.

Connaître l'utilisateur courant#

GET /v1/auth/me renvoie le même objet user que la connexion, complété par is_demo (true pour un utilisateur du cabinet de démonstration). C'est l'appel idéal pour vérifier qu'un jeton est encore valide.

Se déconnecter#

POST /v1/auth/logout révoque le jeton utilisé pour l'appel et répond 204 sans corps.

Jetons d'intégration#

Un jeton d'intégration est conçu pour être confié à une autre solution. Il porte un nom, une liste de capacités, une date d'expiration facultative et la date de sa dernière utilisation.

Capacités#

Les six routes de synchronisation hors ligne n'exigent que sync. Un connecteur qui se contente de suivre les changements avec sync/pull n'a donc besoin ni de read ni de write. La route POST companies/{company}/sync/novadesko, qui relance l'import depuis Novadesko, n'en fait pas partie : elle relève de write.

Créer un jeton#

La création exige un jeton de session : un jeton d'intégration ne peut pas en créer d'autres.

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

Réponse 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
  }
}

Un utilisateur peut détenir 50 jetons d'intégration au maximum. Au-delà, la création répond 422 avec le code token_limit_reached. La route est limitée à 20 créations par minute.

Lister les jetons#

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

Seuls vos propres jetons d'intégration sont listés. Les jetons de session des applications n'y figurent pas.

Révoquer un jeton#

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

La réponse est 204. Le jeton cesse de fonctionner immédiatement. Un identifiant inconnu, ou qui n'est pas un de vos jetons d'intégration, répond 404.

Erreurs d'authentification#

Exemple de refus pour capacité manquante :

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

Bonnes pratiques#

• Un jeton par intégration. Vous pourrez en révoquer un sans interrompre les autres, et la colonne de dernière utilisation restera lisible.
• Le moins de capacités possible. Un outil de reporting n'a besoin que de read.
• Une expiration. Fixez expires_in_days et planifiez le renouvellement avant l'échéance.
• Un utilisateur dédié. Créez dans le cabinet un collaborateur réservé à l'intégration, avec le rôle strictement nécessaire. L'historique montrera clairement ce que l'intégration a fait.
• Un stockage chiffré. Conservez le jeton dans un gestionnaire de secrets ou une variable d'environnement, jamais dans le code source, un dépôt Git ou une application exécutée dans le navigateur de vos clients.
• HTTPS uniquement. N'envoyez jamais le jeton sur une connexion non chiffrée et ne le placez pas dans une URL.

Voir aussi#

• Vue d'ensemble de l'API
• Conventions
• Erreurs et limites
• Rôles et équipe