IRMA for developers: quickstart

This quickstart follows the route that works today: one of your own systems reports an incident to IRMA. You need an organization with IRMA, someone with the Beheerder (administrator) role in IRMA, and a terminal. Everything works with curl; the irma CLI makes it shorter.

The IRMA app is in Dutch; this page quotes its labels in Dutch with an English gloss.

Installing the CLI

The irma CLI is a single Bun program (Bun 1.1 or newer) with no other dependencies. A public install package is still to come. Until then everything on this page also works with curl; for help with the connection, mail support@prudai.com. All commands: CLI reference.

1. Create a service token

A service token is a key of your organization for one system. An administrator creates it:

1. In IRMA, go to Beheer (management) → Service-tokens and click Toevoegen (add).
2. Give the token a Naam (name) that identifies the system, for example monitoring.
3. Under Scopes, choose incidenten aanleveren (incidents:write). If the system should also read incidents back, choose incidenten lezen (incidents:read) as well.
4. Click Token aanmaken (create token) and copy the token right away. You see it only once: IRMA stores a hash only.

A token starts with irma_sk_. Keep it like a password: in a secret store or environment variable, never in code or a ticket. If it leaks, choose Intrekken (revoke). More: IRMA: administration.

2. Check the token

With 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"] }

With the CLI:

printf %s "$IRMA_TOKEN" | irma auth set --stdin   # stores the token with file mode 0600
irma whoami

The API address is https://api.irma.prudai.com. A 401 means the token is unknown or revoked.

3. Report an incident

With 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": "Backup failed on db-01",
    "description": "The nightly backup stopped with exit code 1.",
    "severity": "hoog",
    "source": { "kind": "vps", "name": "db-01", "reference": "https://monitoring.example.com/alerts/4711" },
    "fingerprint": "backup-failed:db-01",
    "occurredAt": "2026-10-24T03:10:00Z"
  }'

With the CLI every write is a dry run first. You see what would be sent; only --no-dry-run --yes sends it:

irma incident create --title "Backup failed on db-01" --severity hoog \
  --description "The nightly backup stopped with exit code 1." \
  --source-kind vps --source-name db-01 --fingerprint backup-failed:db-01
# read the dry run, then:
irma incident create … --no-dry-run --yes

The incident then appears in IRMA under Incidenten, with the reporting system as its source.

Response	Meaning
201	New incident created.
200	The same fingerprint already existed: IRMA counted the report on the existing incident (the occurrence count goes up, the severity only goes up).
400	Invalid input, for example an unknown severity.
401	Token unknown or revoked.
403	The token lacks the incidents:write scope.

Severity is one of laag (low), middel (medium), hoog (high), kritiek (critical). Source (source.kind) is one of agent, vps, status-page, manual, other.

4. Choose a good fingerprint

The fingerprint decides what “the same incident” is. Use something that stays stable while the problem is the same: your alert rule plus the system, such as backup-failed:db-01. Do not put a timestamp in it, or every repeat becomes a new incident. If you leave the fingerprint out, the CLI derives one from source, title and day. More in the recipe SIEM or service desk: incidents into IRMA.

Reading through /v1

With the /v1 task layer you read what is in IRMA, through the CLI or directly (GET https://api.irma.prudai.com/v1/context):

irma context --json                       # organization, roles, read scope, modules, counts
irma risks list --sort=-netScore --limit 10
irma risk-profile compare --from import   # what changed since the import

For /v1 you use, for now, the access token of a signed-in user (same role and read scope as in the app), not a service token. There is no public route yet to get such a token outside the app; scopes for service tokens on /v1 are coming. See Permissions and scopes. Every endpoint with examples: IRMA API reference (Prudai staff only, sign-in required).