Skip to main content

​
Vue d’ensemble

L’API Finkare supporte OAuth 2.1 avec trois grant types :
Grant TypeUsageRefresh Token
Client CredentialsMachine-to-machine (serveur)Non
Authorization Code + PKCEApplication tierce (utilisateur)Oui
Refresh TokenRenouvellement d’access tokenOui

​
Client Credentials

Le flow le plus simple, pour les intégrations serveur-à-serveur sans intervention utilisateur.

​
1. Obtenir un access token

curl -X POST https://api.finkare.io/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "fk_client_mgen_prod",
    "client_secret": "fk_secret_xyz789abc123def456",
    "scope": "invoices:read invoices:write payments:read workflow:read"
  }'
Vous pouvez aussi passer les credentials via Basic Auth : 
curl -X POST https://api.finkare.io/api/oauth/token \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'fk_client_mgen_prod:fk_secret_xyz789abc123def456' | base64)" \
  -d '{ "grant_type": "client_credentials", "scope": "invoices:read payments:read" }'

​
2. Réponse

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

​
3. Utiliser le token

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  https://api.finkare.io/api/v1/invoices
Les tokens Client Credentials expirent après 1 heure (3600 secondes). Demandez un nouveau token avant expiration.

​
Authorization Code + PKCE

Pour les applications qui nécessitent le consentement explicite de l’utilisateur. Obligatoire pour les intégrations qui accèdent à des données multi-entreprises.

​
1. Générer le PKCE challenge

import crypto from 'crypto';

// Générer le code_verifier (43-128 caractères)
const codeVerifier = crypto.randomBytes(32).toString('base64url');

// Calculer le code_challenge (SHA-256)
const codeChallenge = crypto
  .createHash('sha256')
  .update(codeVerifier)
  .digest('base64url');

console.log('code_verifier:', codeVerifier);
console.log('code_challenge:', codeChallenge);

​
2. Rediriger vers l’écran de consentement

GET https://api.finkare.io/api/oauth/authorize
  ?response_type=code
  &client_id=fk_client_votre_app
  &redirect_uri=https://votre-app.com/callback
  &scope=invoices:read+payments:read+workflow:read
  &state=random_csrf_protection_string
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
L’utilisateur voit un écran de consentement Finkare listant les scopes demandés. Après approbation, il est redirigé vers votre redirect_uri avec un code : 
https://votre-app.com/callback?code=auth_abc123xyz&state=random_csrf_protection_string

​
3. É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_votre_app",
    "client_secret": "fk_secret_votre_secret",
    "code": "auth_abc123xyz",
    "redirect_uri": "https://votre-app.com/callback",
    "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
  }'

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

​
4. Renouveler avec le refresh token

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

​
Révocation

Révoquez un token compromis (opération idempotente) : 
curl -X POST https://api.finkare.io/api/oauth/revoke \
  -H "Content-Type: application/json" \
  -d '{ "token": "eyJhbGciOiJSUzI1NiIs..." }'

​
Introspection

Vérifiez la validité d’un token et ses métadonnées : 
curl -X POST https://api.finkare.io/api/oauth/introspect \
  -H "Content-Type: application/json" \
  -d '{ "token": "eyJhbGciOiJSUzI1NiIs..." }'

{
  "active": true,
  "client_id": "fk_client_mgen_prod",
  "scope": "invoices:read payments:read",
  "token_type": "Bearer"
}

​
Discovery (RFC 8414)

Les métadonnées OAuth sont disponibles via le endpoint de discovery : 
GET https://api.finkare.io/.well-known/oauth-authorization-server
Cela permet aux outils compatibles (y compris les clients MCP) de découvrir automatiquement les endpoints OAuth.

​
Bonnes pratiques

  1. Moindre privilège : ne demandez que les scopes strictement nécessaires
  2. Refresh proactif : renouvelez le token quelques minutes avant son expiration
  3. Stockage sécurisé : ne stockez jamais les tokens dans le localStorage — utilisez des cookies httpOnly ou un backend
  4. State parameter : vérifiez toujours le state dans le callback pour prévenir les attaques CSRF
  5. PKCE obligatoire : seule la méthode S256 est acceptée (conformité OAuth 2.1)