irma server
irma server [options...]
The API that this server offers consists of two parts:
- Endpoints under
/irma
. This is used exclusively by the irmaclient/IRMA app, and is not documented here. - Endpoints under
/session
with which IRMA session requestors can start IRMA sessions, monitor their status and retrieve their result afterwards.
API reference
POST /session
DELETE /session/{token}
GET /session/{token}/status
GET /session/{token}/statusevents
GET /session/{token}/result
GET /session/{token}/result-jwt
GET /session/{token}/getproof
GET /publickey
For each of these endpoints, if the HTTP status code indicates that the request was not successful (i.e. not in the 2xx range), then the server returns an irma.RemoteError
instance. For example, attempting to retrieve the session result of an unknown session returns
{"status": 400, "error": "SESSION_UNKNOWN", "description": "Unknown or expired session"}
The following fields may occur in this message:
status
: HTTP error code associated to this errorerror
: an errorType
from the list of possible errors in the server API documentationdescription
: English human-readable description of this errormessage
: May contain additional informationstacktrace
: Stack trace of the error, only if verbose mode is enabled
POST /session
Start an IRMA session. What to POST to this endpoint depends on the server configuration:
- If
no_auth
is true, an (extended) JSON session request - If
no_auth
is false:- (extended) JSON session request with an API token in the
Authorization
HTTP header - JWT session request signed with RS256 or HS256
- (extended) JSON session request with an API token in the
If no_auth
is false, then which of these options should be taken depends on the requestors
option passed to the irma server
.
In each case an appropriate Content-Type
with text/plain
or application/json
must be included.
If the request was successfully parsed, and authenticated if applicable, then the server returns a session package:
{
"token":"KzxuWKwL5KGLKr4uerws",
"sessionPtr": {"u":"https://example.com/irma/ysDohpoySavbHAUDjmpz","irmaqr":"disclosing"}
}
In the endpoints below, the {token}
placeholder must be replaced with the above session token
. The sessionPtr
points to the IRMA session for the IRMA app user, and should be displayed as a QR for the user to scan, or encoded in a universal link for a mobile session, e.g. using irma-frontend
.
Each session starts in the "INITIALIZED"
session status. Regardless of how it reaches its ending status ("DONE"
, "CANCELLED"
, "TIMEOUT"
), it is kept in memory for 5 minutes after reaching its ending status. After that all endpoints below requiring the session token
return error "SESSION_UNKNOWN"
.
DELETE /session/{token}
Cancel the session: set the session status to "CANCELLED"
.
GET /session/{token}/status
Retrieve the session status as a JSON string. Returns one of:
"INITIALIZED"
: the session has been started and is waiting for the client"CONNECTED"
: the client has retrieved the session request, we wait for its response"CANCELLED"
: the session is cancelled: the user refused, or the user did not have the requested attributes, or an error occurred during the session"DONE"
: the session has completed successfully"TIMEOUT"
: session timed out
Of these the latter three are ending statuses; once the session reaches such a status, it will not switch status again. A session starts as "INITIALIZED"
and reaches one of the ending statuses either directly or after becoming "CONNECTED"
.
The session is cancelled and receives status
"CANCELLED"
not only when the IRMA app user refuses, but also when the session is aborted due to an error.
If the session is cancelled due to the user aborting, it is (by design) not possible using this or the other endpoints of the
irma server
to distinguish between (1) the user had the requested attributes but refused to disclose them, and (2) the session was aborted by the user's IRMA app because (s)he did not have the required attributes.
GET /session/{token}/statusevents
Subscribe to a server-sent event stream of status updates. Whenever the session status changes, an event is sent with the new session status as a JSON string. If you need to monitor the status of a session, this is preferred over polling to GET /session/{token}/status
.
GET /session/{token}/result
Get the session result. Example output:
{
"type" : "disclosing",
"status" : "DONE",
"disclosed" : [
[{
"status" : "PRESENT",
"rawvalue" : "yes",
"id" : "irma-demo.MijnOverheid.ageLower.over18",
"value" : {
"en" : "yes",
"nl" : "yes",
"" : "yes"
}
}]
],
"proofStatus" : "VALID",
"token" : "ELMExi5iauWYHzbH7gwU"
}
The response may contain the following fields:
token
: Session tokenstatus
: Current session statustype
: Session type: one of"disclosing"
,"signing"
, or"issuing"
proofStatus
: One of the package level irma.ProofStatus constants, indicating the cryptographic validity of the attributes and proofs of knowledge:"VALID"
: proofs are valid"INVALID"
: proofs are invalid"INVALID_TIMESTAMP"
: Attribute-based signature has invalid timestamp"UNMATCHED_REQUEST"
: proofs do not correspond to a specified request"MISSING_ATTRIBUTES"
: proofs do not contain all requested attributes"EXPIRED"
: Attributes were expired at creation time
disclosed
: List of attributes disclosed by the user. The array structure mirrors that of the session request that started the session: the i-th item of the outer array is a conjunction of attributes satisfying the i-th outer conjunction of the session request. (Note: if the session was started with a legacy, pre-condiscon session request, then this array structure has a different legacy structure; see the legacy documentation)signature
: The full attribute-based signature in case of"signing"
sessionserror
: Error message in case of failure
If the session is not yet finished (that is, the session status is INITIALIZED
or CONNECTED
), then only the first three fields are populated. (For getting just the current session status, using GET /session/{token}/statusevents
or GET /session/{token}/status
is preferred.)
This endpoint just fetches the session result, and works normally even if the session failed. If so, the status
, proofStatus
or error
fields will indicate what happened. Be sure to check these fields when retrieving and handling the session result.
GET /session/{token}/result-jwt
If a JWT private key was provided in the configuration of the irma server
, then this returns a JWT signed by the irma server
with the message from GET /session/{token}/result
above as JWT body, along with the following standard JWT fields:
iss
: name of the currentirma server
as defined in its configurationiat
: Unix timestamp indicating when this JWT was createdsub
:verification_result
orsigning_result
orissuing_result
This way, even if the session result from the irma server
travels along an untrusted route (for example the user's browser), the session result can still be validated and trusted.
GET /session/{token}/getproof
Also returns a session result JWT, but one whose structure is the same as the session JWTs returned by the irma_api_server
. Only works if a JWT private key was provided in the configuration of the irma server
.
GET /publickey
If a JWT private key was provided in the configuration of the irma server
, then this returns the corresponding public key in PEM with which the server's session result JWTs returned by GET /session/{token}/result-jwt
and GET /session/{token}/getproof
can be verified.