API-referentie
heyGRC publieke API: eindpunten voor frameworks en reviewconfiguratie, met request- en responsevormen.
Basis-URL: https://api.heygrc.com
Alle verzoeken authenticeren met een API-sleutel per organisatie als Bearer-token:
Authorization: Bearer hgrc_...Een sleutel behoort tot één heyGRC-organisatie (één per GitHub App-installatie) en bevat scopes (config:read, config:write). Verstuur de sleutel alleen in de header - sleutels die in de URL worden doorgegeven, worden geweigerd (400), om te voorkomen dat ze in logs en verwijzers terechtkomen. De organisatie waarop een verzoek betrekking heeft, wordt altijd afgeleid van de sleutel, dus een sleutel kan alleen de configuratie van zijn eigen organisatie lezen of schrijven.
GET /v1/config
Geeft de huidige configuratie van uw organisatie terug. Scope: config:read.
200
{
"profile": { "company": "Acme Inc", "...": "..." },
"frameworks": ["ISO_27001", "SOC_2", "GDPR"],
"eu_inference": false
}PUT /v1/config
Volledige vervanging van de configuratie van uw organisatie. Idempotent: het body-bericht is de volledige gewenste staat (alles wat u weglaat, wordt gewist). Scope: config:write.
Eén uitzondering op volledige vervanging: eu_inference is optioneel en blijvend. Weglaten laat de huidige waarde van de organisatie ongewijzigd; een boolean stelt de waarde in (niet-booleans worden geweigerd). Vertrouw niet op een weglatende PUT om deze te resetten.
Headers: Content-Type: application/json; optioneel Idempotency-Key: <string> (wordt gelogd voor veilige herhalingen).
Body
| Veld | Type | Opmerkingen |
|---|---|---|
profile | object (verplicht) | Vrije vorm van bedrijfscontext. Moet een JSON-object zijn, ≤ 16 KB, maximale nestdiepte 4, waarden zijn strings / nummers / booleans / arrays daarvan. |
frameworks | string[] (verplicht) | De framework-ids waarmee u moet voldoen. Elke id moet in de catalogus staan - onbekende ids worden geweigerd, niet stilzwijgend genegeerd. |
eu_inference | boolean (optioneel) | Blijvend: weggelaten = huidige waarde blijft; boolean = ingesteld. Niet-booleans worden geweigerd. |
200
{ "ok": true, "profile": { "...": "..." }, "frameworks": ["ISO_27001", "SOC_2", "GDPR"] }Een 200 wordt alleen geretourneerd nadat de wijziging en het bijbehorende auditrecord samen zijn vastgelegd, dus een succesvolle schrijfactie is altijd controleerbaar.
Fouten
Stabiele JSON-vorm bij elke fout:
{ "error": { "code": "unknown_frameworks", "message": "onbekende framework-ids: FOO", "unknown": ["FOO"] } }| Status | code | Betekenis |
|---|---|---|
| 400 | invalid_request | Geen JSON-body, verkeerde body-vorm, of een sleutel werd in de URL doorgegeven. |
| 401 | unauthorized | Ontbrekende, misvormde, ongeldige, verlopen of ingetrokken sleutel. |
| 403 | forbidden | De sleutel heeft niet de vereiste scope (config:read / config:write). |
| 422 | invalid_profile | profile is geen object, is te groot, of is te diep genest. |
| 422 | unknown_frameworks | Een of meer framework-ids staan niet in de catalogus (zie unknown). |
| 429 | rate_limited | Te veel verzoeken; vertraag. |
| 405 | method_not_allowed | HTTP-methode wordt niet ondersteund op dit endpoint. |
| 500 | internal | Onverwachte serverfout; opnieuw proberen met backoff is veilig. |
Snelheidslimieten
Per-sleutel en per-IP-aanvraaglimieten beschermen de service. Blijf onder ongeveer 1 verzoek/seconde en u zult nooit een 429 zien. Configuratie is een control plane - u stelt deze af en toe in, niet in een hot loop.
GET /v1/frameworks
De volledige, machineleesbare catalogus (geen authenticatie - wijs uw agent hierheen om geldige ids te ontdekken):
{ "frameworks": [ { "id": "ISO_27001", "name": "ISO 27001:2022", "region": "International" }, … ] }Frameworkcatalogus
De frameworkcatalogus van heyGRC wordt geretourneerd door GET /v1/frameworks (het aantal groeit in de loop van de tijd; hardcodeer deze niet). Geef de canonieke id door in frameworks. De meest voorkomende ids:
ISO_27001, ISO_42001, ISO_27701, ISO_22301, ISO_9001, SOC_2, GDPR, UK_GDPR, HIPAA,
CCPA, EU_AI_ACT, NIST_CSF, NIST_800_53, NIST_800_171, NIST_AI_RMF, DORA, TISAX,
CMMC, FEDRAMP, CYFUN, AU_ESSENTIAL_EIGHT, en NIS 2 als NIS_2 plus landvarianten
(NIS_2_DE, NIS_2_FR, NIS_2_IT, …).
Een PUT met een id buiten de catalogus wordt geweigerd met 422 unknown_frameworks en de foutieve ids worden teruggegeven, zodat uw agent zichzelf kan corrigeren.