Aller au contenu
Subsido

Démarrer

Authentification

Clés Bearer, clés de production et de test, les routes qui répondent sans clé et la vérification d'une clé.

Clés Bearer

Envoyez votre clé avec chaque requête vers une route qui en demande une, comme jeton bearer dans l’en-tête Authorization.

curl "https://api.subsido.be/v1/subsidies?limit=3" \  -H "Authorization: Bearer sb_live_..."
  • X-API-Key: sb_live_... fonctionne aussi, pour les outils qui ne peuvent pas définir d’en-tête Authorization. Si les deux sont envoyés, Authorization l’emporte.
  • Le schéma ne tient pas compte de la casse (Bearer ou bearer), et une clé envoyée dans Authorization sans schéma est également acceptée.
  • Une clé absente, mal formée ou révoquée donne 401 unauthorized. La réponse ne précise pas lequel des trois cas s’applique, pour que celui qui tente de deviner des clés n’en apprenne rien.
  • Une clé valide sur un compte sans formule donne 402 subscription_required jusqu’au choix d’une formule.
  • L’endpoint MCP, POST /mcp, accepte la même clé dans le même en-tête.

Clés de production et de test

Une clé est créée sous la forme sb_live_… ou sb_test_…. Les deux donnent accès exactement aux mêmes données et sont décomptées de la même façon : quota mensuel, évaluations de matching et limite de débit. Le libellé sert à vous : utilisez des clés de test pour la CI et le développement local, afin de distinguer cette consommation de celle de la production dans le tableau de bord.

Le nombre de clés qu’un compte peut détenir dépend de la formule (voir les tarifs). Une clé n’est affichée qu’une fois, à sa création. Seuls son hachage SHA-256 et ses premiers caractères sont conservés, si bien qu’aucun endpoint ne peut renvoyer une clé : une clé perdue se révoque dans le tableau de bord et se remplace. La révocation prend effet immédiatement.

Gardez les clés côté serveur

Une clé placée dans le JavaScript du navigateur peut être copiée et consommée par n’importe qui. Appelez l’API depuis votre backend et ne transmettez au front-end que ce qu’il doit afficher.

Vérifier une clé

GET /v1/key renvoie la formule de la clé, tout ce qu’elle permet et la consommation du mois, requête en cours comprise. C’est la bonne première requête pour une nouvelle intégration, et un bon contrôle de santé pour une intégration en production. Comme sur toutes les autres routes, la réponse est placée dans data, avec meta à côté.

curl "https://api.subsido.be/v1/key" -H "Authorization: Bearer sb_live_..."
{
  "data": {
    "live": true,
    "plan": {
      "plan": "developer",
      "label": "Developer",
      "price_monthly_eur": 20,
      "price_yearly_eur": 200,
      "price_from_monthly_eur": null,
      "self_serve": true,
      "purchasable": true,
      "monthly_requests": 10000,
      "monthly_match_evaluations": 100,
      "rate_limit_rps": 5,
      "api_keys": 2,
      "max_page_size": 100,
      "max_bulk_companies": 0,
      "watchlist_companies": 0,
      "webhook_endpoints": 0,
      "capabilities": {
        "change_feed": true,
        "history": false,
        "as_of": false,
        "webhooks": false,
        "bulk_match": false,
        "watchlists": false,
        "bulk_export": false,
        "redistribution_rights": false
      }
    },
    "requests_this_month": 1284,
    "match_evaluations_this_month": 37
  },
  "meta": {
    "request_id": "req_01hxyz",
    "warnings": []
  }
}

Routes sans clé

Ces routes publient ce que le site affiche de toute façon. Elles sont limitées par adresse client, ne renvoient pas d’en-têtes RateLimit-* et ne sont décomptées d’aucun quota.

RouteÀ quoi elle sert
GET /v1/healthStatut, version, et quelles sources ne sont pas à jour.
GET /v1/plansLes formules, leurs prix et tout ce que chacune permet.
GET /v1/openapi.jsonLe contrat OpenAPI 3.1.
GET /v1/taxonomyChaque liste fermée de valeurs avec ses libellés en néerlandais, en français et en anglais, les champs et opérateurs des règles, les types d’événements.
GET /v1/coverageLe nombre de mesures, par statut, source, instrument, niveau de pouvoir, région et thème.
GET /v1/sourcesChaque source, avec sa licence, son mode de droits et sa fraîcheur.
GET /v1/sources/{id}Une source, avec ses dix dernières collectes.

Tout le reste, endpoint MCP compris, demande une clé. Sans clé, une route qui en exige une répond 401 ; voir les erreurs.

En-têtes de chaque réponse

En-têteSignification
X-Request-IdL’identifiant de la requête (req_…), également dans meta.request_id ou error.request_id. Indiquez-le si vous nous écrivez.
X-IndependenceLa déclaration d’indépendance : un service indépendant, pas une autorité publique. Lisible par une machine sans passer par le site.
RateLimit-Limit, RateLimit-Remaining, RateLimit-ResetSur les routes avec clé : votre quota mensuel de requêtes, ce qu’il en reste et le nombre de secondes avant sa remise à zéro. Voir limites.
X-Quota-Limit, X-Quota-RemainingLes mêmes chiffres mensuels sous un second nom.