Naar de inhoud
Subsido

Starten

Authenticatie

Bearer-sleutels, live- en testsleutels, de routes die zonder sleutel antwoorden en een sleutel controleren.

Bearer-sleutels

Stuur je sleutel mee met elke request naar een route die een sleutel vraagt, als bearer token in de Authorization-header.

curl "https://api.subsido.be/v1/subsidies?limit=3" \  -H "Authorization: Bearer sb_live_..."
  • X-API-Key: sb_live_... werkt ook, voor tools die geen Authorization-header kunnen zetten. Stuur je beide, dan geldt Authorization.
  • Het schema is niet hoofdlettergevoelig (Bearer of bearer), en een sleutel in Authorization zonder schema wordt ook aanvaard.
  • Een ontbrekende, misvormde of ingetrokken sleutel geeft 401 unauthorized. Het antwoord zegt niet welke van de drie, zodat wie sleutels probeert te raden er niets uit leert.
  • Een geldige sleutel van een account zonder plan geeft 402 subscription_required tot er een plan gekozen is.
  • Het MCP-endpoint, POST /mcp, neemt dezelfde sleutel in dezelfde header.

Live- en testsleutels

Een sleutel wordt aangemaakt als sb_live_… of sb_test_…. Beide geven toegang tot precies dezelfde gegevens en beide tellen op dezelfde manier mee voor je maandquotum, je match-evaluaties en je limiet per seconde. Het label is voor jezelf: gebruik testsleutels voor CI en lokale ontwikkeling, zodat je dat gebruik in het dashboard los van productie ziet.

Hoeveel sleutels een account mag hebben, hangt af van het plan (zie de prijzen). Een sleutel wordt één keer getoond, bij het aanmaken. Alleen de SHA-256-hash en de eerste tekens worden bewaard, dus geen enkel endpoint kan een sleutel teruggeven: een verloren sleutel trek je in het dashboard in en vervang je. Intrekken werkt meteen.

Houd sleutels op de server

Een sleutel in JavaScript in de browser kan iedereen kopiëren en opgebruiken. Roep de API aan vanuit je backend en geef je frontend alleen wat hij moet tonen.

Een sleutel controleren

GET /v1/key geeft het plan van de sleutel, alles wat dat plan toelaat en het gebruik van deze maand, inclusief de request zelf. Het is de juiste eerste request voor een nieuwe integratie en een goede gezondheidscheck voor een draaiende. Zoals op elke andere route zit het antwoord in data, met meta ernaast.

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 zonder sleutel

Deze routes publiceren wat de website toch al toont. Ze zijn begrensd per clientadres, sturen geen RateLimit-*-headers mee en tellen voor geen enkel quotum.

RouteWaarvoor
GET /v1/healthStatus, versie, en welke bronnen niet actueel zijn.
GET /v1/plansDe plannen, hun prijzen en alles wat elk plan toelaat.
GET /v1/openapi.jsonHet contract in OpenAPI 3.1.
GET /v1/taxonomyElke vaste waardenlijst met labels in het Nederlands, Frans en Engels, de regelvelden en operatoren, de eventtypes.
GET /v1/coverageHoeveel maatregelen er zijn, per status, bron, instrument, bestuursniveau, gewest en thema.
GET /v1/sourcesElke bron, met licentie, rechtenmodus en actualiteit.
GET /v1/sources/{id}Eén bron, met de laatste tien inleesrondes.

Al het andere, het MCP-endpoint inbegrepen, vraagt een sleutel. Een route die er een vraagt, antwoordt zonder sleutel met 401; zie fouten.

Headers op elk antwoord

HeaderBetekenis
X-Request-IdDe id van de request (req_…), ook in meta.request_id of error.request_id. Vermeld hem als je ons schrijft.
X-IndependenceDe onafhankelijkheidsverklaring: een onafhankelijke dienst, geen overheid. Leesbaar voor machines zonder de website.
RateLimit-Limit, RateLimit-Remaining, RateLimit-ResetOp routes met sleutel: je maandelijkse quotum aan requests, wat er nog rest, en het aantal seconden tot het opnieuw begint. Zie limieten.
X-Quota-Limit, X-Quota-RemainingDezelfde maandcijfers onder een tweede naam.