Authentification OAuth Billabex | Billabex Developers

Billabex utilise le flux OAuth 2.1 d’autorisation par code avec PKCE pour sécuriser l’accès à l’API. OpenID Connect (OIDC) est disponible dès que vous demandez le scope openid. Ce guide décrit le flux, les fonctionnalités prises en charge, la durée de vie des jetons, le rafraîchissement et l’ensemble des endpoints.

Vue d’ensemble

Dans les grandes lignes :

Vous créez un client OAuth dans le portail développeur, avec ses URI de redirection et ses scopes autorisés.
Votre application redirige l’utilisateur vers l’endpoint d’autorisation, avec les paramètres PKCE et les scopes demandés.
L’utilisateur se connecte, examine le consentement et approuve l’accès.
Vous recevez un code d’autorisation sur votre URI de redirection.
Vous échangez ce code, accompagné du vérificateur PKCE, contre des jetons sur l’endpoint de jeton.
Vous appelez l’API avec le jeton d’accès et le rafraîchissez quand il le faut.

OAuth chez Billabex est :

centré sur l’utilisateur : c’est un utilisateur qui accorde l’accès ;
fondé sur des jetons : aucune clé d’API ;
restreint par scopes : les permissions sont explicites et minimales ;
borné dans le temps : tous les jetons ont une durée de vie limitée.

Types de jetons et durées de vie

Type de jeton	Durée (secondes)	Durée (lisible)	Rôle
Jeton d’accès	3600	1 heure	Appeler l’API publique
Jeton de rafraîchissement	2592000	30 jours	Obtenir de nouveaux jetons d’accès
Code d’autorisation	600	10 minutes	Code temporaire échangé contre des jetons
Jeton d’identité (OIDC)	600	10 minutes	Jeton d’identité, conforme aux bonnes pratiques OIDC

À noter :

La courte durée de vie du jeton d’accès est délibérée.
Le code d’autorisation et le jeton d’identité suivent les bonnes pratiques de sécurité OIDC.
Un jeton expiré est rejeté automatiquement.

Les acteurs

Un flux OAuth met en jeu trois parties :

le propriétaire de la ressource : l’utilisateur qui accorde l’accès ;
l’application cliente : la vôtre ;
le serveur d’autorisation : le serveur OAuth de Billabex.

Votre application ne manipule jamais directement les identifiants de l’utilisateur.

Fonctionnalités OAuth 2.1 prises en charge

Billabex suit les conventions OAuth 2.1 avec des réglages par défaut sûrs.

Flux par code uniquement (response_type=code)
PKCE obligatoire (S256 recommandé, plain accepté pour les clients historiques)
Jetons de rafraîchissement avec rotation à chaque usage
Authentification sur l’endpoint de jeton
- none pour les clients publics
- client_secret_basic ou client_secret_post pour les clients confidentiels
Enregistrement dynamique de client (RFC 7591 et 7592)
Révocation de jeton (RFC 7009)

Le portail développeur crée des clients confidentiels par défaut et n’affiche le client_secret qu’une seule fois.

Les endpoints OAuth

Tous se trouvent sous l’URL de base de l’API.

Autorisation GET [baseURL]/api/oauth/authorize

Jeton POST [baseURL]/api/oauth/token

Révocation POST [baseURL]/api/oauth/revoke

UserInfo (OIDC) GET [baseURL]/api/oauth/userinfo

Enregistrement dynamique POST [baseURL]/api/oauth/register

Gestion de la configuration d’un client GET/PUT/DELETE [baseURL]/api/oauth/register/{clientId}

Découverte et JWKS

Endpoints publics à la racine du domaine :

[baseURL]/.well-known/oauth-authorization-server
[baseURL]/.well-known/openid-configuration
[baseURL]/.well-known/jwks.json
[baseURL]/.well-known/oauth-protected-resource

Métadonnées de ressource protégée (RFC 9728)

Billabex expose l’endpoint de métadonnées de ressource protégée OAuth 2.0, pour qu’un client découvre quel serveur d’autorisation et quels scopes s’appliquent à une ressource.

Pour la ressource /api/public/v1/invoices, l’URL des métadonnées est :

[baseURL]/.well-known/oauth-protected-resource/api/public/v1/invoices

La réponse contient :

authorization_servers, pour la découverte OAuth ;
scopes_supported, pour ce chemin de ressource précis.

La requête d’autorisation

Redirigez l’utilisateur vers l’endpoint d’autorisation avec ces paramètres :

client_id (obligatoire)
redirect_uri (obligatoire, correspondance exacte)
response_type=code (obligatoire)
scope (recommandé ; à défaut, le serveur utilise les scopes autorisés du client)
code_challenge (obligatoire)
code_challenge_method=S256 (recommandé)
state (obligatoire)
nonce (obligatoire avec openid)

Validez toujours state, et nonce en OIDC.

Le code d’autorisation

Après approbation, Billabex redirige vers votre redirect_uri avec :

code
state

Le code d’autorisation :

est valable 10 minutes ;
ne peut être utilisé qu’une seule fois.

Échange du code (authorization_code)

POST [baseURL]/api/oauth/token

Champs obligatoires :

grant_type=authorization_code
code
redirect_uri
code_verifier
client_id
client_secret (clients confidentiels)

Réponse en cas de succès :

{
  "access_token": "...",
  "refresh_token": "...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "...",
  "id_token": "..."
}

id_token n’est présent que si openid a été accordé.

Rafraîchir un jeton d’accès

Un jeton d’accès expire au bout d’une heure. Utilisez le jeton de rafraîchissement pour en obtenir un nouveau.

Politique de rotation

Billabex impose la rotation du jeton de rafraîchissement, ce qui signifie que :

chaque rafraîchissement révoque le jeton de rafraîchissement précédent ;
un nouveau jeton de rafraîchissement est émis à chaque fois ;
seul le dernier jeton émis reste valide.

Deux précisions importantes :

rafraîchir un jeton d’accès ne révoque pas l’accès en soi ;
c’est l’opération de rafraîchissement qui invalide le jeton précédent ;
vous devez donc enregistrer le nouveau jeton immédiatement ;
réutiliser un ancien jeton de rafraîchissement échouera.

La requête de rafraîchissement

POST [baseURL]/api/oauth/token

{
  "grant_type": "refresh_token",
  "refresh_token": "CURRENT_REFRESH_TOKEN",
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET"
}

Réponse :

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

Appeler l’API

Envoyez le jeton d’accès en Bearer dans l’en-tête Authorization, sur tous vos appels.

Les scopes sont contrôlés endpoint par endpoint. Consultez le guide des scopes pour ne demander que le minimum nécessaire.

Révocation

Révoquez les jetons lorsqu’un utilisateur déconnecte votre intégration.

Champs :

token
token_type_hint (facultatif)

OpenID Connect (OIDC)

OIDC s’active dès que le scope openid est demandé.

Scopes OIDC

openid
profile
email

Jeton d’identité

N’est renvoyé que si openid a été accordé
Doit être validé : signature, émetteur, audience, expiration, nonce

Endpoint UserInfo

Renvoie les claims de l’utilisateur autorisés par les scopes accordés.

Bonnes pratiques de sécurité

Utilisez toujours HTTPS
Utilisez toujours PKCE
Validez state et nonce
Stockez les jetons de façon sûre
Faites tourner les jetons de rafraîchissement de manière atomique
Ne journalisez jamais un jeton
Ne demandez que les scopes strictement nécessaires

Pour aller plus loin

Support

Une question sur OAuth ou OIDC ? Écrivez-nous via le formulaire de contact.