Authentification OAuth
Une application s'authentifie via OAuth 2.0 (grant client_credentials) : elle échange ses identifiants contre un jeton d'accès de courte durée, puis appelle l'API v2 avec l'en-tête Authorization: Bearer.
Vue d'ensemble
Permissions (scopes)
Les scopes déterminent les données accessibles. Un appel vers un endpoint dont le scope requis n'a pas été accordé renvoie une erreur 403. Les scopes sensibles sont utilisables en sandbox, mais nécessitent une revue manuelle pour la production.
| Scope | Description | Sensible |
|---|---|---|
enterprise:read | Dénominations, forme juridique, statut, dates clés. | — |
enterprise:address | Adresse du siège social et adresses associées. | — |
enterprise:activities | Codes NACE et activités déclarées de l’entreprise. | — |
enterprise:contact | E-mails, téléphones, fax et site web. Donnée sensible — revue manuelle obligatoire avant la production. | Oui |
enterprise:financial | Comptes annuels et indicateurs financiers (BNB). | — |
enterprise:roles | Administrateurs, gérants et fonctions liées à l’entreprise. | — |
establishment:read | Détail des unités d’établissement et de leurs données. | — |
search | Recherche et listes d’entreprises et d’établissements. | — |
peppol:check | Vérifie l’enregistrement Peppol d’une entreprise. | — |
reference:read | Codes NACE, formes juridiques et autres référentiels. | — |
Obtenir un jeton d'accès
Échangez vos identifiants via POST /api/oauth/token avec grant_type=client_credentials. Les identifiants peuvent être transmis dans le corps de la requête ou via l'en-tête HTTP Basic.
curl -X POST https://companybelgium.be/api/oauth/token \
-d grant_type=client_credentials \
-d client_id=cb_app_live_xxxxxxxxxxxxxxxx \
-d client_secret=cb_secret_live_xxxxxxxxxxxxxxxx{
"access_token": "cbat_xxxxxxxxxxxxxxxxxxxxxxxx",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "enterprise:read search reference:read"
}Le jeton expire après 1 heure. Le grant client_credentials n'émet pas de refresh token — mettez le jeton en cache et redemandez-en un à l'expiration. Le paramètre optionnel scope permet de restreindre le jeton à un sous-ensemble des permissions de l'application.
Appeler l'API v2
Passez le jeton dans l'en-tête Authorization: Bearer. Tous les endpoints v2 l'acceptent, en alternative aux en-têtes X-API-Key / X-API-Secret.
curl https://companybelgium.be/api/v2/enterprise/0200065765 \
-H "Authorization: Bearer cbat_xxxxxxxxxxxxxxxxxxxxxxxx"// 1. Obtenir un jeton (à mettre en cache ~55 min)
const tokenRes = await fetch('https://companybelgium.be/api/oauth/token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'client_credentials',
client_id: process.env.CB_CLIENT_ID,
client_secret: process.env.CB_CLIENT_SECRET,
}),
});
const { access_token } = await tokenRes.json();
// 2. Appeler l'API v2
const res = await fetch(
'https://companybelgium.be/api/v2/enterprise/0200065765',
{ headers: { Authorization: `Bearer ${access_token}` } },
);
console.log(await res.json());import os, requests
token = requests.post(
'https://companybelgium.be/api/oauth/token',
data={
'grant_type': 'client_credentials',
'client_id': os.environ['CB_CLIENT_ID'],
'client_secret': os.environ['CB_CLIENT_SECRET'],
},
).json()['access_token']
res = requests.get(
'https://companybelgium.be/api/v2/enterprise/0200065765',
headers={'Authorization': f'Bearer {token}'},
)
print(res.json())Erreurs d'authentification
| Statut | Cause |
|---|---|
400 | grant_type non supporté ou paramètre manquant. |
401 | client_id / client_secret invalides, ou jeton expiré, révoqué ou inconnu. |
403 | Scope requis non accordé, ou application suspendue. |
429 | Quota mensuel ou limite horaire du plan dépassés. |