Authentification

Aperçu

L’API Smartbills utilisé l’authentification par jeton JWT Bearer. Chaque requête API doit inclure un jeton valide dans l’en-tête Authorization. Les jetons peuvent être obtenus via des clés API ou des flux OAuth2.

Avant de commencer : Vous avez besoin d’un compte Smartbills et de clés API pour vous authentifier. Visitez developers.smartbills.io pour commencer.

En-tête d’authentification

Incluez votre jeton dans l’en-tête Authorization de chaque requête :

GET /v1/expenses HTTP/1.1
Host: api.smartbills.io
Authorization: Bearer VOTRE_CLE_API
Content-Type: application/json
x-tenant-id: 123

Le format de l’en-tête est :

Authorization: Bearer {jeton}

Ou {jeton} est soit :

Une clé API (ex. : sk_live_1234567890abcdef)
Un jeton d’accès OAuth2 obtenu via le point d’accès de jetons

En-tête multi-locataire

Smartbills est une plateforme multi-locataire. Vous devez inclure l’en-tête x-tenant-id pour spécifier le contexte d’entreprise :

x-tenant-id: 123

Cet en-tête indique à l’API les données de quelle entreprise vous souhaitez accéder. Votre jeton doit avoir la permission d’accéder à l’entreprise spécifiée.

En-tête de locale

Utilisez l’en-tête Accept-Language pour recevoir des réponses localisées :

Accept-Language: fr-CA

Locales supportées : en-CA, fr-CA, en-US. Consultez Localisations pour plus de détails.

En-têtes de requête complets

Une requête authentifiee complète inclut ces en-têtes :

GET /v1/expenses HTTP/1.1
Host: api.smartbills.io
Authorization: Bearer VOTRE_CLE_API
Content-Type: application/json
Accept: application/json
x-tenant-id: 123
Accept-Language: fr-CA

Authentification OAuth2

Flux Client Credentials

Utilisez ce flux pour la communication serveur à serveur sans interaction utilisateur. Point d’accès : POST https://api.smartbills.io/auth/connect/token Requête :

POST /auth/connect/token HTTP/1.1
Host: api.smartbills.io
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=VOTRE_CLIENT_ID&client_secret=VOTRE_CLIENT_SECRET

Réponse :

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Exemples de code

curl --request POST \
  --url https://api.smartbills.io/auth/connect/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials' \
  --data 'client_id=VOTRE_CLIENT_ID' \
  --data 'client_secret=VOTRE_CLIENT_SECRET'

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

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

// Le SDK géré automatiquement la gestion des jetons.
// Pour les flux OAuth2 manuels :
const tokenResponse = await fetch('https://api.smartbills.io/auth/connect/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'VOTRE_CLIENT_ID',
    client_secret: 'VOTRE_CLIENT_SECRET'
  })
});

const { access_token, expires_in } = await tokenResponse.json();

from smartbills import SmartbillsClient
import requests

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

# Le SDK géré automatiquement la gestion des jetons.
# Pour les flux OAuth2 manuels :
token_response = requests.post(
    'https://api.smartbills.io/auth/connect/token',
    data={
        'grant_type': 'client_credentials',
        'client_id': 'VOTRE_CLIENT_ID',
        'client_secret': 'VOTRE_CLIENT_SECRET'
    }
)

token_data = token_response.json()
access_token = token_data['access_token']
expires_in = token_data['expires_in']

Flux Authorization Code

Utilisez ce flux pour les applications orientees utilisateur ou vous devez agir au nom d’un utilisateur. Étape 1 : Rediriger vers le point d’accès d’autorisation

GET /auth/connect/authorize?response_type=code&client_id=VOTRE_CLIENT_ID&redirect_uri=VOTRE_URI_REDIRECTION&scope=expenses.read expenses.write
Host: api.smartbills.io

Étape 2 : Echanger le code d’autorisation contre un jeton d’accès

POST /auth/connect/token HTTP/1.1
Host: api.smartbills.io
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=CODE_AUTORISATION&redirect_uri=VOTRE_URI_REDIRECTION&client_id=VOTRE_CLIENT_ID&client_secret=VOTRE_CLIENT_SECRET

Réponse :

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_abcdef123456..."
}

Expiration et rafraîchissement des jetons

Les jetons d’accès expirent après une période definie (généralement 3600 secondes / 1 heure). Utilisez le champ expires_in pour savoir quand un jeton expirera.

Rafraîchir les jetons

Lorsque votre jeton d’accès expiré, utilisez le jeton de rafraîchissement pour en obtenir un nouveau :

curl --request POST \
  --url https://api.smartbills.io/auth/connect/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=refresh_token' \
  --data 'refresh_token=VOTRE_REFRESH_TOKEN' \
  --data 'client_id=VOTRE_CLIENT_ID' \
  --data 'client_secret=VOTRE_CLIENT_SECRET'

async function refreshAccessToken(refreshToken) {
  const response = await fetch('https://api.smartbills.io/auth/connect/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      refresh_token: refreshToken,
      client_id: 'VOTRE_CLIENT_ID',
      client_secret: 'VOTRE_CLIENT_SECRET'
    })
  });

  const { access_token, refresh_token, expires_in } = await response.json();
  return { access_token, refresh_token, expires_in };
}

def refresh_access_token(refresh_token):
    response = requests.post(
        'https://api.smartbills.io/auth/connect/token',
        data={
            'grant_type': 'refresh_token',
            'refresh_token': refresh_token,
            'client_id': 'VOTRE_CLIENT_ID',
            'client_secret': 'VOTRE_CLIENT_SECRET'
        }
    )
    return response.json()

Rotation des jetons de rafraîchissement : Chaque fois que vous utilisez un jeton de rafraîchissement, un nouveau jeton de rafraîchissement est retourné. L’ancien jeton est invalide. Stockez toujours le dernier jeton de rafraîchissement.

Utilisation des SDK

Les SDK officiels gerent automatiquement l’authentification, le rafraîchissement des jetons et la gestion des en-têtes :

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

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

// Le SDK inclut automatiquement les en-tetes Authorization et x-tenant-id
const expenses = await client.expenses.list();

from smartbills import SmartbillsClient

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

# Le SDK inclut automatiquement les en-tetes Authorization et x-tenant-id
expenses = client.expenses.list()

Erreurs d’authentification

Statut HTTP	Code d’erreur	Description
401	`UNAUTHORIZED`	Clé API manquante ou invalide
401	`API_KEY_EXPIRED`	La clé API à expiré
401	`API_KEY_REVOKED`	La clé API a été révoquée
401	`INVALID_TOKEN`	Jeton JWT invalide ou mal forme
403	`FORBIDDEN`	Le jeton n’a pas les permissions requises
403	`BUSINESS_ACCESS_DENIED`	Aucun accès à l’entreprise spécifiée

Bonnes pratiques de sécurité

Protéger vos identifiants

Stockez les clés API et les secrets dans des variables d’environnement
Ne commitez jamais les identifiants dans le contrôle de version
N’exposez jamais les jetons dans le code côté client
Utilisez HTTPS pour toutes les requêtes API

Utiliser les portées appropriees

Demandez uniquement les portées dont votre application a besoin
Utilisez des portées en lecture seule quand l’accès en écriture n’est pas nécessaire
Révisez et auditez les portées régulièrement

Gérer l'expiration des jetons

Vérifiez la valeur expires_in après avoir obtenu les jetons
Implémentez le rafraîchissement automatique des jetons avant l’expiration
Gérez les erreurs 401 en rafraichissant et en retentant

Rotation régulière des clés

Effectuez la rotation des clés API tous les 90 jours
Révoquez immédiatement les clés compromises
Utilisez des clés séparées pour chaque environnement

Ressources connexes

Clés API

Créer et gérer les clés API

Environnements

Environnements bac à sable et production

Gestion des erreurs

Gérer les erreurs d’authentification

Limites de débit

Comprendre la limitation de débit

Getting Started

Core Concepts

Expenses

Business Expenses

Expense Reports

Mileage

Approvals

Bills & Accounts Payable

Vendors

Vault

Team & Administration

Settings

Mobile App

Aperçu

En-tête d’authentification

En-tête multi-locataire

En-tête de locale

En-têtes de requête complets

Authentification OAuth2

Flux Client Credentials

Exemples de code

Flux Authorization Code

Expiration et rafraîchissement des jetons

Rafraîchir les jetons

Utilisation des SDK

Erreurs d’authentification

Bonnes pratiques de sécurité

Ressources connexes

Clés API

Environnements

Gestion des erreurs

Limites de débit

​Aperçu

​En-tête d’authentification

​En-tête multi-locataire

​En-tête de locale

​En-têtes de requête complets

​Authentification OAuth2

​Flux Client Credentials

​Exemples de code

​Flux Authorization Code

​Expiration et rafraîchissement des jetons

​Rafraîchir les jetons

​Utilisation des SDK

​Erreurs d’authentification

​Bonnes pratiques de sécurité

​Ressources connexes

Clés API

Environnements

Gestion des erreurs

Limites de débit

Aperçu

En-tête d’authentification

En-tête multi-locataire

En-tête de locale

En-têtes de requête complets

Authentification OAuth2

Flux Client Credentials

Exemples de code

Flux Authorization Code

Expiration et rafraîchissement des jetons

Rafraîchir les jetons

Utilisation des SDK

Erreurs d’authentification

Bonnes pratiques de sécurité

Ressources connexes