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