---
title: "IRMA for developers: quickstart"
description: "Your first incident in IRMA in five minutes: create a service token, check it with irma whoami or curl, and report an incident through /agent/v1 with a fingerprint against duplicates. Plus reading through /v1."
editUrl: true
head: []
template: "doc"
sidebar: {"hidden":false,"attrs":{}}
pagefind: true
draft: false
---

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](https://bun.sh) 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](/en/irma-cli).

## 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](/en/irma-beheer#service-tokens).

## 2. Check the token

With curl:

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

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

With the CLI:

```sh
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:

```sh
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:

```sh
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](/en/irma-developers-recipes#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`):

```sh
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](/en/irma-developers-concepts#permissions-and-scopes). Every endpoint with examples: [IRMA API reference](/en/irma/api) (Prudai staff only, sign-in required).