Skip to content

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.

The npm package @prudai/irma is available on npm, including irma auth login. Everything on this page also works with curl; for help with the connection, mail support@prudai.com.

The irma CLI is an npm package with no other dependencies. You need Node.js 20 or newer.

Terminal window
npm i -g @prudai/irma # installs the irma command
irma --version
# or without installing:
npx @prudai/irma --help

All commands: CLI reference.

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.

With curl:

Terminal window
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:

Terminal window
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.

With curl:

Terminal window
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:

Terminal window
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.

ResponseMeaning
201New incident created.
200The same fingerprint already existed: IRMA counted the report on the existing incident (the occurrence count goes up, the severity only goes up).
400Invalid input, for example an unknown severity.
401Token unknown or revoked.
403The 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.

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.

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

Terminal window
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 a personal token (the same role and read scope you have in the app), not a service token. You get it with irma auth login:

Terminal window
irma auth login
# Open https://app.prudai.com/irma/cli-koppelen?code=ABCD-EFGH
# Code: ABCD-EFGH
  1. The CLI opens the CLI koppelen (connect CLI) page in your browser. Working over SSH or in WSL without a browser? Open the printed link yourself on a computer where you are signed in to IRMA.
  2. Check that the code and the device match what your terminal shows, choose the organization if asked, and click Toestaan (allow).
  3. The CLI stores the token (irma_pat_…) with file mode 0600 and shows as whom and in which organization you are connected.

The token is valid for 90 days, works on /v1 only and acts with exactly your rights. IRMA treats it as an agent: writes fall under the per-action approval for agents. You see and revoke your tokens under Instellingen (settings) → Persoonlijke tokens (personal tokens); from the terminal with irma auth logout. irma auth status shows who, which organization and until when. See Permissions and scopes. Every endpoint with examples: IRMA API reference (Prudai staff only, sign-in required).