Authentification

Vue d’ensemble

L’API Finkare supporte deux méthodes d’authentification :

Méthode	Usage	Complexité
API Key	Intégrations serveur-à-serveur (M2M)	Simple
OAuth 2.1	Applications tierces, flux utilisateur	Avancé

API Key

Méthode recommandée pour les intégrations backend. Incluez votre clé dans le header X-API-Key :

curl -H "X-API-Key: fk_live_abc123def456ghi789jkl012mno345" \
  https://api.finkare.io/api/v1/invoices

Préfixes

Préfixe	Environnement	Description
`fk_live_`	Production	Actions réelles (envois email, SMS, LRAR)
`fk_test_`	Sandbox	Aucune action réelle, données de test

Gestion des clés

Endpoint	Méthode	Description	Scope requis
`POST /api/v1/api-keys`	Créer	Génère une nouvelle clé (retournée une seule fois)	`webhooks:manage`
`GET /api/v1/api-keys`	Lister	Liste les clés masquées	`webhooks:manage`
`POST /api/v1/api-keys/:id/rotate`	Rotation	Génère une nouvelle clé, désactive l’ancienne	`webhooks:manage`
`DELETE /api/v1/api-keys/:id`	Révoquer	Désactive une clé (soft delete)	`webhooks:manage`

La clé API est affichée une seule fois à la création. Stockez-la dans un gestionnaire de secrets (AWS Secrets Manager, HashiCorp Vault, etc.). Ne la commitez jamais dans votre code source.

Exemple de rotation

curl -X POST https://api.finkare.io/api/v1/api-keys/550e8400-e29b-41d4-a716-446655440000/rotate \
  -H "X-API-Key: fk_live_votre_cle_admin"

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "apiKey": "fk_live_nouveau_secret_genere_ici_abc",
    "prefix": "fk_live_nouv...e_abc"
  },
  "message": "Key rotated. Save the new key — it will not be shown again."
}

OAuth 2.1

Pour les applications tierces qui agissent au nom d’un utilisateur Finkare. Trois grant types supportés :

Client Credentials (M2M)

Authentification serveur-à-serveur sans intervention utilisateur.

curl -X POST https://api.finkare.io/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "fk_client_abc123",
    "client_secret": "fk_secret_xyz789",
    "scope": "invoices:read payments:read workflow:read"
  }'

Réponse :

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "invoices:read payments:read workflow:read"
}

Utilisez ensuite le token Bearer :

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  https://api.finkare.io/api/v1/invoices

Authorization Code + PKCE

Pour les applications qui nécessitent le consentement de l’utilisateur. Seule la méthode PKCE S256 est supportée (conformité OAuth 2.1).

Générer le code challenge

import crypto from 'crypto';

const codeVerifier = crypto.randomBytes(32).toString('base64url');
const codeChallenge = crypto
  .createHash('sha256')
  .update(codeVerifier)
  .digest('base64url');

Rediriger vers l'écran de consentement

GET https://api.finkare.io/api/oauth/authorize
  ?response_type=code
  &client_id=fk_client_abc123
  &redirect_uri=https://votre-app.com/callback
  &scope=invoices:read+payments:read
  &state=random_state_string
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

Échanger le code contre un token

curl -X POST https://api.finkare.io/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "fk_client_abc123",
    "client_secret": "fk_secret_xyz789",
    "code": "auth_code_recu_dans_callback",
    "redirect_uri": "https://votre-app.com/callback",
    "code_verifier": "le_code_verifier_original"
  }'

Refresh Token

Renouvelez un access token expiré sans redemander le consentement :

curl -X POST https://api.finkare.io/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "client_id": "fk_client_abc123",
    "refresh_token": "fk_rt_abc123xyz789"
  }'

Révocation et introspection

Endpoint	Description
`POST /api/oauth/revoke`	Révoque un token (RFC 7009, idempotent)
`POST /api/oauth/introspect`	Vérifie la validité d’un token (RFC 7662)

Scopes

Chaque clé API ou token OAuth est associé à un ensemble de scopes qui définissent les permissions :

Scope	Description
`invoices:read`	Lire les factures et leurs statuts
`invoices:write`	Créer et mettre à jour des factures
`invoices:delete`	Supprimer des factures (avant lancement workflow)
`debtors:read`	Lire les informations des débiteurs
`debtors:write`	Créer et mettre à jour des débiteurs
`payments:read`	Consulter les paiements reçus
`payments:write`	Gérer les paiements
`workflow:read`	Consulter le statut et l’historique des workflows
`workflow:trigger`	Déclencher des actions (start, pause, resume, escalate)
`webhooks:manage`	Gérer les webhooks et les clés API
`reports:read`	Accéder aux statistiques et rapports
`agent:chat`	Interagir avec l’assistant IA Bob
`lrar:send`	Déclencher l’envoi de LRAR
`notifications:send`	Envoyer des notifications (email, SMS)
`scoring:read`	Consulter les scores de solvabilité IA

Appliquez le principe du moindre privilège : n’attribuez que les scopes strictement nécessaires à votre intégration.

Rate Limiting

Les limites varient selon votre tier de souscription :

Tier	Requêtes/min	Requêtes/jour	Import en masse
Starter	60	10 000	100 factures/requête
Pro	300	100 000	100 factures/requête
Enterprise	1 000+	Illimité	100 factures/requête

Headers de réponse

Chaque réponse inclut les headers de rate limiting :

Header	Description
`X-RateLimit-Limit`	Limite par minute pour votre tier
`X-RateLimit-Remaining`	Requêtes restantes dans la fenêtre
`X-RateLimit-Reset`	Timestamp UNIX de réinitialisation
`X-RateLimit-Daily-Remaining`	Requêtes restantes pour la journée
`Retry-After`	Secondes à attendre (si code 429)

Gestion du rate limiting

// Le SDK gère automatiquement le retry sur 429
const finkare = new FinkareClient('fk_live_xxx', {
  maxRetries: 3, // Retry jusqu'à 3 fois avec backoff exponentiel
});

En cas de dépassement (429 Too Many Requests), attendez le nombre de secondes indiqué par le header Retry-After avant de retenter.

Sécurité

HTTPS obligatoire : toutes les requêtes doivent utiliser HTTPS
IP Whitelist : restreignez l’accès à vos IPs de production
Rotation régulière : faites tourner vos clés tous les 90 jours
Idempotency-Key : utilisez le header Idempotency-Key sur les POST pour éviter les doublons en cas de retry réseau
X-Request-Id : chaque réponse contient un ID unique pour le support

Get Started

Changelog

Vue d’ensemble

API Key

Préfixes

Gestion des clés

Exemple de rotation

OAuth 2.1

Client Credentials (M2M)

Authorization Code + PKCE

Refresh Token

Révocation et introspection

Scopes

Rate Limiting

Headers de réponse

Gestion du rate limiting

Sécurité

​Vue d’ensemble

​API Key

​Préfixes

​Gestion des clés

​Exemple de rotation

​OAuth 2.1

​Client Credentials (M2M)

​Authorization Code + PKCE

​Refresh Token

​Révocation et introspection

​Scopes

​Rate Limiting

​Headers de réponse

​Gestion du rate limiting

​Sécurité

Vue d’ensemble

API Key

Préfixes

Gestion des clés

Exemple de rotation

OAuth 2.1

Client Credentials (M2M)

Authorization Code + PKCE

Refresh Token

Révocation et introspection

Scopes

Rate Limiting

Headers de réponse

Gestion du rate limiting

Sécurité