Clés API

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.

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.

Créer des clés API

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

Naviguer vers les clés API

Connectez-vous à app.smartbills.io
Cliquez sur votre icône de profil (en haut à droite)
Sélectionnez Paramètres
Naviguez vers Développeur > Clés API

Créer une nouvelle clé

Cliquez sur Créer une nouvelle clé API
Entrez un nom descriptif pour la clé (ex. : “Serveur de production”, “Environnement de développement”)
(Optionnel) Définissez une date d’expiration
(Optionnel) Restreignez à des adresses IP spécifiques
Cliquez sur Générer la clé

Copier votre clé

Votre clé API sera affichée une seule fois
Copiez-la immédiatement dans un emplacement sécurisé
Stockez-la dans votre gestionnaire de mots de passe ou vos variables d’environnement
Cliquez sur J’ai sauvegarde ma clé pour confirmer

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.

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

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.

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

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.

Utiliser les clés API

En-tête d’authentification

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

Authorization: Bearer VOTRE_CLE_API

Exemple complet

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'

import { SmartbillsClient } from '@smartbills/sdk';

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

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

from smartbills import SmartbillsClient

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

expenses = client.expenses.list()

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 sous scopes_supported.

Portées entreprises

businesses.read - Voir les informations des entreprises, lister les entreprises, obtenir les détailsbusinesses.write - Créer de nouvelles entreprises, mettre à jour les informations, modifier les paramètres

Portées dépenses

expenses.read - Lister les dépenses, obtenir les détails, télécharger les pièces jointes, exporter les donnéesexpenses.write - Téléverser des dépenses, mettre à jour les informations, ajouter ou supprimer des pièces jointes, catégoriserreceipts.read / receipts.write - Accéder aux reçus sous-jacents et les modifier

Portées rapports de dépenses

expense-reports.read - Lister les rapports, obtenir les détails, voir la chronologieexpense-reports.write - Créer des rapports, mettre à jour les détails, ajouter ou supprimer des dépensesexpense-reports.submit - Soumettre des rapports pour approbationexpense-reports.approve / expense-reports.reject - Agir sur les rapports en attente de votre approbationexpense-reports.reimburse - Marquer des rapports comme remboursés

Portées comptes fournisseurs

bills.read / bills.write - Accéder aux factures et les modifiervendors.read / vendors.write - Accéder aux fournisseurs et les modifier

Portées identité

openid - Requis pour tout flux OpenID Connectprofile, email, phone, address, full_name - Revendications sur l’utilisateur connectéoffline_access - Émettre un jeton de rafraîchissement avec le jeton d’accès

Portées plateforme

webhooks.read / webhooks.write - Gérer les points de terminaison webhookdevelopers.read / developers.write - Gérer les paramètres développeurnotifications.read / notifications.write - Accéder aux notifications et les gérer

Gérer les clés API

Révoquer des clés

Désactivez immédiatement une clé API :

Naviguez vers votre liste de clés API
Trouvez la clé à révoquer
Cliquez sur Révoquer ou l’icône de corbeille
Confirmez l’action

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.

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.

Créer une nouvelle clé

Générez une nouvelle clé API avec les mêmes permissions.

Mettre à jour votre application

Remplacez l’ancienne clé par la nouvelle dans votre application. Testez soigneusement.

Surveiller

Surveillez les requêtes utilisant encore l’ancienne clé. Vérifiez l’horodatage “Dernière utilisation”.

Révoquer l'ancienne clé

Une fois que vous êtes sur que la nouvelle clé fonctionne, révoquez l’ancienne.

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.

Bonnes pratiques de sécurité

Stocker dans des variables d’environnement

# Fichier .env (ne jamais commiter !)
SMARTBILLS_API_KEY=sk_live_1234567890abcdef
SMARTBILLS_BUSINESS_ID=123

// Utiliser dans votre code
const apiKey = process.env.SMARTBILLS_API_KEY;

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

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

Dépannage

Erreur 401 Non autorisé

Causes possibles :

En-tête Authorization manquant - Incluez Authorization: Bearer VOTRE_CLE_API
Format incorrect - Assurez-vous que le préfixe “Bearer ” est inclus sans espaces supplémentaires
Clé révoquée ou expirée - Vérifiez si la clé est toujours active dans le tableau de bord
Mauvais type de clé - Utilisez sk_live_ pour la production et sk_test_ pour le bac à sable

Erreur 403 Interdit

Causes possibles :

Permissions insuffisantes - Votre compte utilisateur n’a pas les permissions nécessaires
Restriction IP - Requête depuis une adresse IP non autorisée
Accès à l’entreprise - Tentative d’accès à une entreprise dont vous n’êtes pas membre

Impossible de créer une clé API

Causes possibles :

Limite de clés atteinte - Plan gratuit : 2 clés max, Professionnel : 10 clés max, Entreprise : Illimité
Permissions insuffisantes - Seuls les propriétaires de compte et les administrateurs peuvent créer des clés API

Ressources connexes

Authentification

Documentation complète d’authentification

Environnements

Environnements bac à sable et production

Limites de débit

Comprendre la limitation de débit de l’API

Gestion des erreurs

Gérer les erreurs API efficacement

Getting Started

Core Concepts

Expenses

Business Expenses

Expense Reports

Mileage

Approvals

Bills & Accounts Payable

Vendors

Vault

Team & Administration

Settings

Mobile App

Aperçu

Créer des clés API

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

Types de clés API

Clés de test

Clés de production

Utiliser les clés API

En-tête d’authentification

Exemple complet

Permissions et portées des clés

Heritage des permissions

Portées disponibles

Gérer les clés API

Révoquer des clés

Rotation des clés

Bonnes pratiques de sécurité

Stocker dans des variables d’environnement

Utiliser des clés différentes par environnement

A eviter

Dépannage

Ressources connexes

Authentification

Environnements

Limites de débit

Gestion des erreurs

​Aperçu

​Créer des clés API

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

​Types de clés API

​Clés de test

​Clés de production

​Utiliser les clés API

​En-tête d’authentification

​Exemple complet

​Permissions et portées des clés

​Heritage des permissions

​Portées disponibles

​Gérer les clés API

​Révoquer des clés

​Rotation des clés

​Bonnes pratiques de sécurité

​Stocker dans des variables d’environnement

​Utiliser des clés différentes par environnement

​A eviter

​Dépannage

​Ressources connexes

Authentification

Environnements

Limites de débit

Gestion des erreurs

Aperçu

Créer des clés API

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

Types de clés API

Clés de test

Clés de production

Utiliser les clés API

En-tête d’authentification

Exemple complet

Permissions et portées des clés

Heritage des permissions

Portées disponibles

Gérer les clés API

Révoquer des clés

Rotation des clés

Bonnes pratiques de sécurité

Stocker dans des variables d’environnement

Utiliser des clés différentes par environnement

A eviter

Dépannage

Ressources connexes