API-Referenz
heyGRC öffentliche API: Endpunkte für Frameworks und Review-Konfiguration mit Anfrage- und Antwortstrukturen.
Basis-URL: https://api.heygrc.com
Alle Anfragen authentifizieren sich mit einem organisationsspezifischen API-Schlüssel als Bearer-Token:
Authorization: Bearer hgrc_...Ein Schlüssel gehört zu einer heyGRC-Organisation (einer pro GitHub-App-Installation) und verfügt über Bereiche (config:read, config:write). Senden Sie den Schlüssel nur im Header – Schlüssel, die in der URL übergeben werden, werden abgelehnt (400), um ein Leaken in Protokolle und Referrer zu vermeiden. Die Organisation, auf die eine Anfrage wirkt, wird immer vom Schlüssel abgeleitet, sodass ein Schlüssel nur die Konfiguration seiner eigenen Organisation lesen oder schreiben kann.
GET /v1/config
Gibt die aktuelle Konfiguration Ihrer Organisation zurück. Bereich: config:read.
200
{
"profile": { "company": "Acme Inc", "...": "..." },
"frameworks": ["ISO_27001", "SOC_2", "GDPR"],
"eu_inference": false
}PUT /v1/config
Vollständiger Ersatz der Konfiguration Ihrer Organisation. Idempotent: Der Body ist der vollständige gewünschte Zustand (alles, was weggelassen wird, wird gelöscht). Bereich: config:write.
Eine Ausnahme vom vollständigen Ersatz: eu_inference ist optional und persistent. Wird es weggelassen, bleibt der aktuelle Wert der Organisation unverändert; ein Boolean setzt den Wert (Nicht-Booleans werden abgelehnt). Verlassen Sie sich nicht auf ein weglassendes PUT, um es zurückzusetzen.
Header: Content-Type: application/json; optional Idempotency-Key: <string> (wird für sichere Wiederholungen protokolliert).
Body
| Feld | Typ | Hinweise |
|---|---|---|
profile | object (erforderlich) | Freiform-Firmenkontext. Muss ein JSON-Objekt sein, ≤ 16 KB, maximale Verschachtelungstiefe 4, Werte sind Zeichenketten / Zahlen / boolesche Werte / Arrays davon. |
frameworks | string[] (erforderlich) | Die Framework-IDs, mit denen Sie konform sein müssen. Jede ID muss im Katalog enthalten sein – unbekannte IDs werden abgelehnt, nicht stillschweigend ignoriert. |
eu_inference | Boolean (optional) | Persistent: weggelassen = aktueller Wert bleibt; Boolean = wird gesetzt. Nicht-Booleans werden abgelehnt. |
200
{ "ok": true, "profile": { "...": "..." }, "frameworks": ["ISO_27001", "SOC_2", "GDPR"] }Ein 200 wird nur zurückgegeben, nachdem die Änderung und ihr Audit-Eintrag gemeinsam committed wurden, sodass ein erfolgreicher Schreibvorgang immer auditierbar ist.
Fehler
Stabile JSON-Struktur bei jedem Fehler:
{ "error": { "code": "unknown_frameworks", "message": "unbekannte Framework-IDs: FOO", "unknown": ["FOO"] } }| Status | code | Bedeutung |
|---|---|---|
| 400 | invalid_request | Kein JSON-Body, falsche Body-Struktur oder ein Schlüssel wurde in der URL übergeben. |
| 401 | unauthorized | Fehlender, falsch formatierter, ungültiger, abgelaufener oder widerrufener Schlüssel. |
| 403 | forbidden | Dem Schlüssel fehlt der erforderliche Bereich (config:read / config:write). |
| 422 | invalid_profile | profile ist kein Objekt, zu groß oder zu tief verschachtelt. |
| 422 | unknown_frameworks | Eine oder mehrere Framework-IDs sind nicht im Katalog enthalten (siehe unknown). |
| 429 | rate_limited | Zu viele Anfragen; verlangsamen Sie das Tempo. |
| 405 | method_not_allowed | HTTP-Methode wird auf diesem Endpunkt nicht unterstützt. |
| 500 | internal | Unerwarteter Serverfehler; Wiederholung mit Backoff ist sicher. |
Ratenbegrenzung
Pro-Schlüssel- und Pro-IP-Anfragegrenzen schützen den Dienst. Bleiben Sie unter ~1 Anfrage/Sekunde, und Sie werden nie ein 429 sehen. Die Konfiguration ist eine Steuerungsebene – Sie setzen sie gelegentlich, nicht in einer heißen Schleife.
GET /v1/frameworks
Der vollständige, maschinenlesbare Katalog (keine Authentifizierung – richten Sie Ihren Agenten hierhin, um gültige IDs zu entdecken):
{ "frameworks": [ { "id": "ISO_27001", "name": "ISO 27001:2022", "region": "International" }, … ] }Framework-Katalog
heyGRC kennt den Live-Katalog. Übergeben Sie die kanonische ID in frameworks. Die häufigsten 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, und NIS 2 als NIS_2 sowie länderspezifische Varianten (NIS_2_DE, NIS_2_FR, NIS_2_IT, …).
Eine PUT-Anfrage mit einer ID außerhalb des Katalogs wird mit 422 unknown_frameworks abgelehnt, und die fehlerhaften IDs werden zurückgegeben, sodass Ihr Agent sich selbst korrigieren kann.