---
title: "Authentification OAuth Billabex"
description: "Flux d'autorisation OAuth 2.1 par code avec PKCE, et OpenID Connect en option."
canonical: https://developer.billabex.com/fr/guides/oauth/
lang: fr
alternate: https://developer.billabex.com/en/guides/oauth/
last-updated: 2026-10-05
---

# Authentification OAuth Billabex

> Flux d'autorisation OAuth 2.1 par code avec PKCE, et OpenID Connect en option.

Source: https://developer.billabex.com/fr/guides/oauth/
Langue: Français (fr)
Version anglaise: https://developer.billabex.com/en/guides/oauth/

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 :

1. Vous créez un client OAuth dans le portail développeur, ou dans la webapp Billabex sur **Mon compte → Mes clients OAuth**, avec ses URI de redirection et ses scopes autorisés.
2. Votre application redirige l'utilisateur vers l'endpoint d'autorisation, avec les paramètres PKCE et les scopes demandés.
3. L'utilisateur se connecte, examine le consentement et approuve l'accès.
4. Vous recevez un code d'autorisation sur votre URI de redirection.
5. Vous échangez ce code, accompagné du vérificateur PKCE, contre des jetons sur l'endpoint de jeton.
6. 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.

## Gestion des applications

Créez, modifiez, supprimez vos applications et renouvelez leur secret depuis le portail développeur
ou **Mon compte → Mes clients OAuth** dans la webapp. Le nouveau secret n'est affiché qu'une fois
et remplace immédiatement l'ancien pour les échanges qui exigent ce secret.

Les routes privées `/api/oauth/clients` du portail exigent une session active. Leurs écritures
exigent aussi un en-tête `Origin` égal à l'origine du portail de cet environnement. Le navigateur
le transmet automatiquement ; une demande provenant d'un autre site ou sans cet en-tête est
refusée avec un statut 403. Cela s'applique aussi au POST sans corps de renouvellement du secret.
Les appels manuels avec un cookie doivent fournir cette origine. Cette règle ne change pas les
endpoints OAuth d'autorisation, d'échange ou de rafraîchissement des jetons utilisés par votre application.

## 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 https://next.billabex.com/api/oauth/authorize`

**Jeton**
`POST https://next.billabex.com/api/oauth/token`

**Révocation**
`POST https://next.billabex.com/api/oauth/revoke`

**UserInfo (OIDC)**
`GET https://next.billabex.com/api/oauth/userinfo`

**Enregistrement dynamique**
`POST https://next.billabex.com/api/oauth/register`

**Gestion de la configuration d'un client**
`GET/PUT/DELETE https://next.billabex.com/api/oauth/register/{clientId}`

### Découverte et JWKS

Endpoints publics à la racine du domaine :

- `https://next.billabex.com/.well-known/oauth-authorization-server`
- `https://next.billabex.com/.well-known/openid-configuration`
- `https://next.billabex.com/.well-known/jwks.json`
- `https://next.billabex.com/.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 :

`https://next.billabex.com/.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.

Billabex vérifie le client et sa destination de retour avant toute redirection, y compris
en cas d'erreur ou de refus du consentement. Un client inconnu ou supprimé, ou une destination
non autorisée, reçoit HTTP 400 sur Billabex, sans redirection vers le callback. Un refus pour
un client et un callback valides revient au callback avec `error=access_denied` et `state`.
Si la configuration du client change pendant le consentement, le serveur vérifie la liste
de destinations courante au moment du clic.

Les permissions approuvées doivent appartenir aux scopes autorisés du client. Billabex
revérifie cette limite au moment du consentement, y compris si l'utilisateur arrive
directement sur cet écran. Une demande vide, inconnue ou dépassant cette limite est refusée
avant la création du code et l'enregistrement du consentement. Le serveur ne remplace pas
une liste vide par les permissions par défaut à cette étape.

## 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 https://next.billabex.com/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 :

```json
{
  "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 https://next.billabex.com/api/oauth/token`

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

Réponse :

```json
{
  "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](/fr/guides/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

- **[Démarrage](/fr/guides/demarrage/)**
- **[Scopes OAuth](/fr/guides/scopes/)**
- **[Limites de débit](/fr/guides/limites-de-debit/)**
- **[Référence de l'API](/fr/reference-api/)**

## Support

Une question sur OAuth ou OIDC ?
Écrivez-nous via le [formulaire de contact](https://www.billabex.com/fr/contactez-nous/).

---

Billabex developer portal. OpenAPI specification: https://developer.billabex.com/openapi.json.
Agent instructions: https://developer.billabex.com/llms.txt. Complete documentation: https://developer.billabex.com/llms-full.txt.