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

# Clés API

> Apprenez à créer, gérer et securiser vos clés API Smartbills

## Aperçu

Les clés API sont la méthode principale d'authentification avec l'API Smartbills. Chaque clé est liée à votre compte utilisateur et hérité de vos permissions. Ce guide couvre tout ce que vous devez savoir sur la création, l'utilisation et la gestion sécurisée des clés API.

<Note>
  **Les clés API sont puissantes** : Elles fournissent un accès complet à votre compte via l'API. Traitez-les comme des mots de passe et ne les partagez jamais publiquement.
</Note>

## Créer des clés API

### Générer votre première clé API

<Steps>
  <Step title="Naviguer vers les clés API">
    1. Connectez-vous à [app.smartbills.io](https://app.smartbills.io)
    2. Cliquez sur votre icône de profil (en haut à droite)
    3. Sélectionnez **Paramètres**
    4. Naviguez vers **Développeur** > **Clés API**
  </Step>

  <Step title="Créer une nouvelle clé">
    1. Cliquez sur **Créer une nouvelle clé API**
    2. Entrez un nom descriptif pour la clé (ex. : "Serveur de production", "Environnement de développement")
    3. (Optionnel) Définissez une date d'expiration
    4. (Optionnel) Restreignez à des adresses IP spécifiques
    5. Cliquez sur **Générer la clé**
  </Step>

  <Step title="Copier votre clé">
    1. Votre clé API sera affichée **une seule fois**
    2. Copiez-la immédiatement dans un emplacement sécurisé
    3. Stockez-la dans votre gestionnaire de mots de passe ou vos variables d'environnement
    4. Cliquez sur **J'ai sauvegarde ma clé** pour confirmer
  </Step>
</Steps>

<Warning>
  **Important** : Les clés API ne sont affichées qu'une seule fois lors de la création. Si vous perdez une clé, vous devez la révoquer et en créer une nouvelle.
</Warning>

## Types de clés API

Smartbills fournit deux types de clés API pour différents environnements :

### Clés de test

```
sk_test_1234567890abcdef...
```

**Utilisation :**

* Développement et tests
* Environnements de pre-production
* Tests d'intégration
* Apprentissage de l'API

**Caracteristiques :**

* Préfixe : `sk_test_`
* Données de test séparées
* Limites de débit plus elevees pour les tests
* Aucune charge ou transaction réelle
* Peut être partagée en toute sécurité avec votre équipe de développement

<Tip>
  Les clés de test sont parfaites pour le développement. Elles fonctionnent avec tous les points d'accès mais operent sur des données de test séparées qui n'affectent pas la production.
</Tip>

### Clés de production

```
sk_live_1234567890abcdef...
```

**Utilisation :**

* Environnements de production
* Applications en direct
* Traitement réel des dépenses
* Intégrations de production

**Caracteristiques :**

* Préfixe : `sk_live_`
* Données de production réelles
* Limites de débit standard
* Traite les dépenses réelles
* Doit être hautement sécurisée

<Warning>
  **Sécurité** : Ne commitez jamais les clés de production dans le contrôle de version et ne les exposez jamais dans le code côté client.
</Warning>

## Utiliser les clés API

### En-tête d'authentification

Incluez votre clé API dans l'en-tête `Authorization` de chaque requête :

```http theme={null}
Authorization: Bearer VOTRE_CLE_API
```

### Exemple complet

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.smartbills.io/v1/expenses \
    --header 'Authorization: Bearer sk_live_1234567890abcdef' \
    --header 'Content-Type: application/json' \
    --header 'x-tenant-id: 123'
  ```

  ```javascript JavaScript theme={null}
  import { SmartbillsClient } from '@smartbills/sdk';

  const client = new SmartbillsClient({
    accessToken: 'VOTRE_CLE_API',
    businessId: 123
  });

  const expenses = await client.expenses.list();
  ```

  ```python Python theme={null}
  from smartbills import SmartbillsClient

  client = SmartbillsClient(access_token="VOTRE_CLE_API", business_id=123)

  expenses = client.expenses.list()
  ```
</CodeGroup>

## Permissions et portées des clés

### Heritage des permissions

Les clés API héritent des permissions de l'utilisateur qui les à créées. Si vous avez accès à plusieurs entreprises, votre clé fonctionnera avec toutes via l'en-tête `x-tenant-id`.

### Portées disponibles

Les portées suivent le format `ressource.action`. La liste complète et faisant autorité est publiée
sur [`/auth/.well-known/openid-configuration`](https://api.smartbills.io/auth/.well-known/openid-configuration)
sous `scopes_supported`.

<AccordionGroup>
  <Accordion title="Portées entreprises" icon="building">
    **businesses.read** - Voir les informations des entreprises, lister les entreprises, obtenir les détails

    **businesses.write** - Créer de nouvelles entreprises, mettre à jour les informations, modifier les paramètres
  </Accordion>

  <Accordion title="Portées dépenses" icon="receipt">
    **expenses.read** - Lister les dépenses, obtenir les détails, télécharger les pièces jointes, exporter les données

    **expenses.write** - Téléverser des dépenses, mettre à jour les informations, ajouter ou supprimer des pièces jointes, catégoriser

    **receipts.read** / **receipts.write** - Accéder aux reçus sous-jacents et les modifier
  </Accordion>

  <Accordion title="Portées rapports de dépenses" icon="file-invoice">
    **expense-reports.read** - Lister les rapports, obtenir les détails, voir la chronologie

    **expense-reports.write** - Créer des rapports, mettre à jour les détails, ajouter ou supprimer des dépenses

    **expense-reports.submit** - Soumettre des rapports pour approbation

    **expense-reports.approve** / **expense-reports.reject** - Agir sur les rapports en attente de votre approbation

    **expense-reports.reimburse** - Marquer des rapports comme remboursés
  </Accordion>

  <Accordion title="Portées comptes fournisseurs" icon="file-invoice-dollar">
    **bills.read** / **bills.write** - Accéder aux factures et les modifier

    **vendors.read** / **vendors.write** - Accéder aux fournisseurs et les modifier
  </Accordion>

  <Accordion title="Portées identité" icon="user">
    **openid** - Requis pour tout flux OpenID Connect

    **profile**, **email**, **phone**, **address**, **full\_name** - Revendications sur l'utilisateur connecté

    **offline\_access** - Émettre un jeton de rafraîchissement avec le jeton d'accès
  </Accordion>

  <Accordion title="Portées plateforme" icon="gear">
    **webhooks.read** / **webhooks.write** - Gérer les points de terminaison webhook

    **developers.read** / **developers.write** - Gérer les paramètres développeur

    **notifications.read** / **notifications.write** - Accéder aux notifications et les gérer
  </Accordion>
</AccordionGroup>

## Gérer les clés API

### Révoquer des clés

Désactivez immédiatement une clé API :

1. Naviguez vers votre liste de clés API
2. Trouvez la clé à révoquer
3. Cliquez sur **Révoquer** ou l'icône de corbeille
4. Confirmez l'action

<Warning>
  **Effet immédiat** : La revocation d'une clé arrete immédiatement toutes les requêtes utilisant cette clé. Assurez-vous d'avoir une clé de remplacement en place avant la revocation.
</Warning>

**Quand révoquer :**

* La clé a été compromise ou exposée
* Un employé ayant l'accès à quitte l'organisation
* Migration vers une nouvelle clé
* Intégration plus utilisée
* Utilisation non autorisée suspectee

### Rotation des clés

Bonne pratique : effectuez la rotation des clés régulièrement.

<Steps>
  <Step title="Créer une nouvelle clé">
    Générez une nouvelle clé API avec les mêmes permissions.
  </Step>

  <Step title="Mettre à jour votre application">
    Remplacez l'ancienne clé par la nouvelle dans votre application. Testez soigneusement.
  </Step>

  <Step title="Surveiller">
    Surveillez les requêtes utilisant encore l'ancienne clé. Vérifiez l'horodatage "Dernière utilisation".
  </Step>

  <Step title="Révoquer l'ancienne clé">
    Une fois que vous êtes sur que la nouvelle clé fonctionne, révoquez l'ancienne.
  </Step>
</Steps>

<Tip>
  **Calendrier de rotation** : Effectuez la rotation des clés API tous les 90 jours pour les environnements de production, ou chaque fois que les membres de l'équipe ayant l'accès changent.
</Tip>

## Bonnes pratiques de sécurité

### Stocker dans des variables d'environnement

```bash theme={null}
# Fichier .env (ne jamais commiter !)
SMARTBILLS_API_KEY=sk_live_1234567890abcdef
SMARTBILLS_BUSINESS_ID=123
```

```javascript theme={null}
// Utiliser dans votre code
const apiKey = process.env.SMARTBILLS_API_KEY;
```

```python theme={null}
import os
api_key = os.environ.get('SMARTBILLS_API_KEY')
```

### Utiliser des clés différentes par environnement

* **Développement** : clé de test (`sk_test_...`)
* **Pre-production** : clé de test séparée
* **Production** : clé de production (`sk_live_...`)

N'utilisez jamais la même clé dans plusieurs environnements.

### A eviter

<Warning>
  **Ne faites jamais ceci :**

  * Commiter les clés API dans le contrôle de version (Git, SVN, etc.)
  * Exposer les clés dans le code côté client (bundles JavaScript, applications mobiles)
  * Partager les clés par courriel, Slack ou autres messageries
  * Coder en dur les clés dans le code source
  * Utiliser les clés de production en développement
  * Stocker les clés dans des fichiers non chiffres
  * Inclure les clés dans les URL ou paramètres de requête
  * Enregistrer les clés API dans les journaux d'application
</Warning>

## Dépannage

<AccordionGroup>
  <Accordion title="Erreur 401 Non autorisé" icon="lock">
    **Causes possibles :**

    1. **En-tête Authorization manquant** - Incluez `Authorization: Bearer VOTRE_CLE_API`
    2. **Format incorrect** - Assurez-vous que le préfixe "Bearer " est inclus sans espaces supplémentaires
    3. **Clé révoquée ou expirée** - Vérifiez si la clé est toujours active dans le tableau de bord
    4. **Mauvais type de clé** - Utilisez `sk_live_` pour la production et `sk_test_` pour le bac à sable
  </Accordion>

  <Accordion title="Erreur 403 Interdit" icon="ban">
    **Causes possibles :**

    1. **Permissions insuffisantes** - Votre compte utilisateur n'a pas les permissions nécessaires
    2. **Restriction IP** - Requête depuis une adresse IP non autorisée
    3. **Accès à l'entreprise** - Tentative d'accès à une entreprise dont vous n'êtes pas membre
  </Accordion>

  <Accordion title="Impossible de créer une clé API" icon="circle-exclamation">
    **Causes possibles :**

    1. **Limite de clés atteinte** - Plan gratuit : 2 clés max, Professionnel : 10 clés max, Entreprise : Illimité
    2. **Permissions insuffisantes** - Seuls les propriétaires de compte et les administrateurs peuvent créer des clés API
  </Accordion>
</AccordionGroup>

## Ressources connexes

<CardGroup cols={2}>
  <Card title="Authentification" icon="shield" href="/fr/api-reference/authentication">
    Documentation complète d'authentification
  </Card>

  <Card title="Environnements" icon="server" href="/fr/api-reference/environments">
    Environnements bac à sable et production
  </Card>

  <Card title="Limites de débit" icon="gauge" href="/fr/api-reference/rate-limits">
    Comprendre la limitation de débit de l'API
  </Card>

  <Card title="Gestion des erreurs" icon="triangle-exclamation" href="/fr/api-reference/errors">
    Gérer les erreurs API efficacement
  </Card>
</CardGroup>