IRMA voor ontwikkelaars: snelstart

Deze snelstart volgt de route die vandaag werkt: een eigen systeem levert een incident aan in IRMA. Je hebt nodig: een organisatie met IRMA, iemand met de rol Beheerder in IRMA, en een terminal. Alles kan met curl; met de irma-CLI gaat het korter.

De CLI installeren

De irma-CLI is één Bun-programma (Bun 1.1 of nieuwer) zonder verdere afhankelijkheden. Een openbaar installatiepakket komt nog. Tot die tijd doe je alles op deze pagina ook met curl; voor hulp bij de aansluiting mail je support@prudai.com. Alle commando’s: CLI-referentie.

1. Maak een service-token aan

Een service-token is een sleutel van je organisatie voor één systeem. Een beheerder maakt hem aan:

1. Ga in IRMA naar Beheer → Service-tokens en klik op Toevoegen.
2. Geef het token een Naam waaraan je het systeem herkent, bijvoorbeeld monitoring.
3. Kies bij Scopes incidenten aanleveren (incidents:write). Wil het systeem ook incidenten teruglezen, kies dan ook incidenten lezen (incidents:read).
4. Klik op Token aanmaken en kopieer het token meteen. Je ziet het maar één keer: IRMA bewaart alleen een hash.

Een token begint met irma_sk_. Bewaar hem zoals een wachtwoord: in een secret store of omgevingsvariabele, nooit in code of een ticket. Lekt hij, kies dan Intrekken. Meer: IRMA: beheer.

2. Controleer het token

Met curl:

export IRMA_TOKEN='irma_sk_…'
curl -s https://api.irma.prudai.com/agent/v1/whoami \
  -H "Authorization: Bearer $IRMA_TOKEN"

{ "organizationId": "3f1c…", "tokenName": "monitoring", "scopes": ["incidents:write"] }

Met de CLI:

printf %s "$IRMA_TOKEN" | irma auth set --stdin   # bewaart het token met bestandsrechten 0600
irma whoami

Het adres van de API is https://api.irma.prudai.com. Krijg je 401, dan is het token onbekend of ingetrokken.

3. Lever een incident aan

Met curl:

curl -s -X POST https://api.irma.prudai.com/agent/v1/incidents \
  -H "Authorization: Bearer $IRMA_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Back-up mislukt op db-01",
    "description": "De nachtelijke back-up stopte met exitcode 1.",
    "severity": "hoog",
    "source": { "kind": "vps", "name": "db-01", "reference": "https://monitoring.example.nl/alerts/4711" },
    "fingerprint": "backup-failed:db-01",
    "occurredAt": "2026-10-24T03:10:00Z"
  }'

Met de CLI is elke schrijfactie eerst een droogloop. Je ziet wat er verstuurd zou worden; pas met --no-dry-run --yes gaat het echt:

irma incident create --title "Back-up mislukt op db-01" --severity hoog \
  --description "De nachtelijke back-up stopte met exitcode 1." \
  --source-kind vps --source-name db-01 --fingerprint backup-failed:db-01
# lees de droogloop, dan:
irma incident create … --no-dry-run --yes

Het incident staat daarna in IRMA onder Incidenten, met als bron het systeem dat het aanleverde.

Antwoord	Betekenis
201	Nieuw incident aangemaakt.
200	Dezelfde fingerprint bestond al: IRMA telde de melding op bij het bestaande incident (het aantal keer stijgt, de ernst gaat alleen omhoog).
400	De invoer klopt niet, bijvoorbeeld een onbekende severity.
401	Token onbekend of ingetrokken.
403	Het token mist de scope incidents:write.

Ernst is een van laag, middel, hoog, kritiek. Bron (source.kind) is een van agent, vps, status-page, manual, other.

4. Kies een goede fingerprint

De fingerprint bepaalt wat “hetzelfde incident” is. Neem iets dat stabiel is zolang het probleem hetzelfde is: de regel van je alarm plus het systeem, zoals backup-failed:db-01. Zet er geen tijdstip in, anders wordt elke herhaling een nieuw incident. Laat je de fingerprint weg in de CLI, dan maakt die er een van bron, titel en dag. Meer in het recept SIEM of servicedesk koppelen.

Lezen via /v1

Met de taaklaag /v1 lees je wat er in IRMA staat, met de CLI of rechtstreeks (GET https://api.irma.prudai.com/v1/context):

irma context --json                       # organisatie, rollen, leesscope, modules, tellingen
irma risks list --sort=-netScore --limit 10
irma risk-profile compare --from import   # wat veranderde er sinds de import

Voor /v1 gebruik je voorlopig het toegangstoken van een ingelogde gebruiker (dezelfde rol en leesscope als in de app), niet een service-token. Een openbare route om zo’n token buiten de app te krijgen is er nog niet; scopes voor service-tokens op /v1 komen eraan. Zie Rechten en scopes. Alle endpoints met voorbeelden: IRMA API-referentie (alleen voor Prudai-medewerkers, inloggen vereist).