Clés API - Smartbills

Aperçu

Les clés API sont la méthode principale d’authentification avec l’API Smartbills. Chaque clé est liee à 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évoquér et en créer une nouvelle.

Types de clés API

Smartbills fournit deux types de clés API pour differents 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 :

Prefixe : 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 :

Prefixe : 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.

Portees disponibles

Portees entreprises

read:businesses - Voir les informations des entreprises, lister les entreprises, obtenir les détailswrite:businesses - Créer de nouvelles entreprises, mettre à jour les informations, modifier les paramètresdelete:businesses - Supprimer des entreprises (avec confirmation)

Portees dépenses

read:expenses - Lister toutes les dépenses, obtenir les détails, télécharger les pieces jointes, exporter les donnéeswrite:expenses - Télécharger de nouvelles dépenses, mettre à jour les informations, ajouter/supprimer des pieces jointes, catégoriserdelete:expenses - Supprimer des dépenses individuelles, opérations de suppression en lot

Portees rapports

read:reports - Lister les rapports, obtenir les détails, voir la chronologie, accéder aux journaux d’auditwrite:reports - Créer de nouveaux rapports, mettre à jour les détails, ajouter/supprimer des dépenses, soumettreapprove:reports - Approuver les rapports, rejeter, demander des changements, ajouter des commentaires

Portees utilisateurs

read:user - Obtenir les détails de son propre utilisateur, voir les paramètreswrite:user - Mettre à jour le profil, changer les paramètresmanage:users - Inviter des utilisateurs, supprimer des utilisateurs, mettre à jour les permissions (administrateur uniquement)

Gérer les clés API

Revoquer des clés

Désactivez immédiatement une clé API :

Naviguez vers votre liste de clés API
Trouvez la clé à révoquér
Cliquez sur Revoquer 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évoquér :

La clé à été compromise ou exposee
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 regulierement.

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”.

Revoquer l'ancienne clé

Une fois que vous etes sur que la nouvelle clé fonctionne, révoquéz 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 differentes 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 prefixe “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’etes 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 : Illimite
Permissions insuffisantes - Seuls les proprietaires 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

​Aperçu

​Créer des clés API

Aperçu

Créer des clés API