> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finkare.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentification

> Deux méthodes d'authentification : API Key pour les intégrations serveur-à-serveur, OAuth 2.1 pour les applications tierces.

## 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` :

```bash theme={null}
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` |

<Warning>
  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.
</Warning>

### Exemple de rotation

```bash theme={null}
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"
```

```json theme={null}
{
  "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.

```bash theme={null}
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 :

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "invoices:read payments:read workflow:read"
}
```

Utilisez ensuite le token Bearer :

```bash theme={null}
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).

<Steps>
  <Step title="Générer le code challenge">
    ```typescript theme={null}
    import crypto from 'crypto';

    const codeVerifier = crypto.randomBytes(32).toString('base64url');
    const codeChallenge = crypto
      .createHash('sha256')
      .update(codeVerifier)
      .digest('base64url');
    ```
  </Step>

  <Step title="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
    ```
  </Step>

  <Step title="Échanger le code contre un token">
    ```bash theme={null}
    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"
      }'
    ```
  </Step>
</Steps>

### Refresh Token

Renouvelez un access token expiré sans redemander le consentement :

```bash theme={null}
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 |

<Tip>
  Appliquez le **principe du moindre privilège** : n'attribuez que les scopes strictement nécessaires à votre intégration.
</Tip>

## 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

```typescript theme={null}
// 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.