Authentification

Toutes les API fiskaly utilisent l’authentification basée sur JWT. Ce guide couvre les différents schémas d’authentification entre les produits.

Flux d’authentification

Clé API + Secret  →  POST /auth (ou /tokens)  →  access_token + refresh_token
                                                       │
                                                       ├─ Utiliser dans l'header Authorization
                                                       │
                                                       └─ Sur 401 → rafraîchir ou se ré-authentifier

SIGN DE, SIGN AT, DSFINVK DE, RECEIPT

Ces produits utilisent un endpoint d’authentification simple :

cURLJavaScriptPython

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

Réponse

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

Champ	Description
access_token	Token JWT valable 24 heures — inclure comme Authorization: Bearer <token>
refresh_token	Token valable 48 heures — utiliser pour obtenir un nouveau token d’accès

SIGN ES

SIGN ES encapsule la requête d’authentification dans une enveloppe content :

cURLJavaScriptPython

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

Ces API plus récentes utilisent /tokens avec le discriminateur content.type et nécessitent des headers supplémentaires :

cURLJavaScriptPython

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

Authentification avec portée

Pour limiter les requêtes à une UNIT organisationnelle spécifique, incluez le header X-Scope-Identifier :

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

Rafraîchissement du token

Lorsque le token d’accès expire, utilisez le token de rafraîchissement au lieu de vous ré-authentifier avec les identifiants :

cURLJavaScriptPython

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

Bonnes pratiques

💡Mettez les tokens en cache

Les tokens d’accès sont valables 24 heures. Mettez le token en cache et ne le rafraîchissez qu’en cas de réponse 401. Se ré-authentifier à chaque requête gaspille ~100ms par appel.

⚠️N'exposez jamais les secrets

• Stockez les secrets API dans des variables d’environnement ou un gestionnaire de secrets - Ne commitez jamais les secrets dans le code source - N’incluez jamais les secrets dans le code côté client - Faites pivoter les clés API si un secret est compromis

Stratégie de token recommandée

1. Authentifiez-vous une fois au démarrage de l’application
2. Stockez access_token et refresh_token en mémoire
3. En cas de réponse 401, tentez de rafraîchir avec le refresh_token
4. Si le rafraîchissement échoue (token expiré), ré-authentifiez-vous avec la clé API + secret
5. Si la ré-authentification échoue, exposez l’erreur à l’opérateur

Connexe

URL de base et environnements

Tous les endpoints API et les détails des environnements

Codes d'erreur

Codes d'erreur d'authentification et dépannage

Concepts fondamentaux

Organisations, environnements et modèle de ressources