Commands
Your application (client) can send some commands (cmd) to control the AusweisApp. The AusweisApp (server) will send some proper Messages during the whole workflow or as an answer to your command.
GET_INFO
Returns information about the current installation of AusweisApp.
The AusweisApp will send an INFO message as an answer.
{"cmd": "GET_INFO"}
GET_STATUS
Returns information about the current workflow and state of AusweisApp.
The AusweisApp will send a STATUS message as an answer.
New in version 1.24.0: Support of GET_STATUS command in API_LEVEL 2.
{"cmd": "GET_STATUS"}
GET_API_LEVEL
Returns information about the available and current API level.
The AusweisApp will send an API_LEVEL message as an answer.
{"cmd": "GET_API_LEVEL"}
SET_API_LEVEL
Set supported API level of your application.
If you initially develop your application against the AusweisApp SDK you should check with GET_API_LEVEL the highest supported level and set this value with this command if you connect to the SDK. This will set the SDK to act with the defined level even if a newer level is available.
The AusweisApp will send an API_LEVEL message as an answer.
level: Supported API level of your app.
{
"cmd": "SET_API_LEVEL",
"level": 1
}
GET_READER
Returns information about the requested reader.
If you explicitly want to ask for information of a known reader name you can request it with this command.
The AusweisApp will send a READER message as an answer.
name: Name of the reader.
{
"cmd": "GET_READER",
"name": "NAME OF THE READER"
}
GET_READER_LIST
Returns information about all connected readers.
If you explicitly want to ask for information of all connected readers you can request it with this command.
The AusweisApp will send a READER_LIST message as an answer.
{"cmd": "GET_READER_LIST"}
RUN_AUTH
Starts an authentication.
The AusweisApp will send an AUTH message when the authentication is started.
The system dialog on iOS can be customized by messages. This dialog won’t be stopped by default after an ENTER_PIN, ENTER_CAN and ENTER_PUK. Command INTERRUPT allows to stop the dialog manually, if needed.
Changed in version 1.24.0: Parameter handleInterrupt removed with API_LEVEL v2 and defaults to false.
New in version 1.24.0: Parameter status added.
New in version 1.22.3: Parameter developerMode added.
New in version 1.22.1: Parameter handleInterrupt and messages added.
Deprecated since version 1.22.1: Parameter handleInterrupt has been removed with API_LEVEL v2
and defaults to false.
tcTokenURL: URL to the TcToken. This is equal to the desktop style activation URL. (http://127.0.0.1:24727/eID-Client?tcTokenURL=)
developerMode: True to enable “Developer Mode” for test cards and disable some security checks according to BSI TR-03124-1, otherwise false. (optional, default: false)
handleInterrupt: True to automatically handle system dialog on iOS, otherwise false. API_LEVEL v1 only. (optional, default: false)
status: True to enable automatic STATUS messages, otherwise false. API_LEVEL v2 only. (optional, default: true)
messages: Messages for the system dialog on iOS. (optional, default: empty)
sessionStarted: Shown if scanning is started.
sessionFailed: Shown if communication was stopped with an error.
sessionSucceeded: Shown if communication was stopped successfully.
sessionInProgress: Shown if communication is in progress. This message will be appended with current percentage level.
{
"cmd": "RUN_AUTH",
"tcTokenURL": "https://test.governikus-eid.de/AusweisAuskunft/WebServiceRequesterServlet",
"developerMode": false,
"handleInterrupt": false,
"status": true,
"messages":
{
"sessionStarted": "Please place your ID card on the top of the device's back side.",
"sessionFailed": "Scanning process failed.",
"sessionSucceeded": "Scanning process has been finished successfully.",
"sessionInProgress": "Scanning process is in progress."
}
}
Note
This command is allowed only if the AusweisApp has no running authentication or other workflow. Otherwise you will get a BAD_STATE message as an answer.
RUN_CHANGE_PIN
Starts a change PIN workflow.
The AusweisApp will send a CHANGE_PIN message when the workflow is started.
The system dialog on iOS can be customized by messages. This dialog won’t be stopped by default after an ENTER_PIN, ENTER_CAN, ENTER_NEW_PIN and ENTER_PUK. Command INTERRUPT allows to stop the dialog manually, if needed.
Changed in version 1.24.0: Parameter handleInterrupt removed with API_LEVEL v2 and defaults to false.
New in version 1.24.0: Parameter status added.
New in version 1.22.1: Parameter handleInterrupt and messages added.
Deprecated since version 1.22.1: Parameter handleInterrupt has been removed with API_LEVEL v2
and defaults to false.
New in version 1.22.0: Support of RUN_CHANGE_PIN command.
handleInterrupt: True to automatically handle system dialog on iOS, otherwise false. API_LEVEL v1 only. (optional, default: false)
status: True to enable automatic STATUS messages, otherwise false. API_LEVEL v2 only. (optional, default: true)
messages: Messages for the system dialog on iOS. (optional, default: empty)
sessionStarted: Shown if scanning is started.
sessionFailed: Shown if communication was stopped with an error.
sessionSucceeded: Shown if communication was stopped successfully.
sessionInProgress: Shown if communication is in progress. This message will be appended with current percentage level.
{
"cmd": "RUN_CHANGE_PIN",
"handleInterrupt": false,
"status": true,
"messages":
{
"sessionStarted": "Please place your ID card on the top of the device's back side.",
"sessionFailed": "Scanning process failed.",
"sessionSucceeded": "Scanning process has been finished successfully.",
"sessionInProgress": "Scanning process is in progress."
}
}
Note
This command is allowed only if the AusweisApp has no running authentication or other workflow. Otherwise you will get a BAD_STATE message as an answer.
GET_ACCESS_RIGHTS
Returns information about the requested access rights.
The AusweisApp will send an ACCESS_RIGHTS message as an answer.
{"cmd": "GET_ACCESS_RIGHTS"}
Note
This command is allowed only if the AusweisApp sends an initial ACCESS_RIGHTS message. Otherwise you will get a BAD_STATE message as an answer.
SET_ACCESS_RIGHTS
Set effective access rights.
By default the effective access rights are optional + required. If you want to enable or disable some optional access rights you can send this command to modify the effective access rights.
The AusweisApp will send an ACCESS_RIGHTS message as an answer.
chat: List of enabled optional access rights. If you send an empty [] all optional access rights are disabled.
{
"cmd": "SET_ACCESS_RIGHTS",
"chat": []
}
{
"cmd": "SET_ACCESS_RIGHTS",
"chat": ["FamilyName"]
}
Note
This command is allowed only if the AusweisApp sends an initial ACCESS_RIGHTS message. Otherwise you will get a BAD_STATE message as an answer.
See also
List of possible access rights are listed in ACCESS_RIGHTS.
SET_CARD
Insert “virtual” card.
Since API_LEVEL 2 it is possible to provide a “virtual” card. The information whether this is possible will be indicated in a READER message.
New in version 1.24.0: This command was introduced in API_LEVEL 2.
New in version 1.26.4: Parameter keys added.
name: Name of the READER.
simulator: Specific data for Simulator. (optional)
files: Content of card Filesystem.
keys: Keys of card Filesystem.
{
"cmd": "SET_CARD",
"name": "reader name",
"simulator":
{
"files": [],
"keys": []
}
}
Note
This command is allowed only if the AusweisApp sends an initial INSERT_CARD message. Otherwise you will get a BAD_STATE message as an answer.
GET_CERTIFICATE
Returns the certificate of current authentication.
The AusweisApp will send a CERTIFICATE message as an answer.
{"cmd": "GET_CERTIFICATE"}
Note
This command is allowed only if the AusweisApp sends an initial ACCESS_RIGHTS message. Otherwise you will get a BAD_STATE message as an answer.
CANCEL
Cancel the whole workflow.
If your application sends this command the AusweisApp will cancel the workflow. You can send this command in any state of a running workflow to abort it.
{"cmd": "CANCEL"}
Note
This command is allowed only if the AusweisApp started an authentication or the CHANGE_PIN workflow. Otherwise you will get a BAD_STATE message as an answer.
ACCEPT
Accept the current state.
If the AusweisApp will send the message ACCESS_RIGHTS the user needs to accept or cancel. So the workflow is paused until your application sends this command to accept the requested information.
If the user does not accept the requested information your application needs to send the command CANCEL to abort the whole workflow.
This command will be used later for additional requested information if the AusweisApp needs to pause the workflow. In API_LEVEL v1 only ACCESS_RIGHTS needs to be accepted.
{"cmd": "ACCEPT"}
Note
This command is allowed only if the AusweisApp sends an initial ACCESS_RIGHTS message. Otherwise you will get a BAD_STATE message as an answer.
INTERRUPT
Interrupts current system dialog on iOS.
If your application provides false to parameter handleInterrupt in RUN_AUTH or RUN_CHANGE_PIN and you need to request more information from the user, you need to interrupt the system dialog manually.
This command will be used later for additional information if your application needs to interrupt the workflow. Currently only the iOS system dialog can be interrupted.
New in version 1.22.1: Support of INTERRUPT command.
{"cmd": "INTERRUPT"}
Note
This command is allowed only if the AusweisApp sends a ENTER_PIN, ENTER_CAN, ENTER_NEW_PIN or ENTER_PUK message. Otherwise you will get a BAD_STATE message as an answer.
SET_PIN
Set PIN of inserted card.
If the AusweisApp sends message ENTER_PIN you need to send this command to unblock the card with the PIN.
The AusweisApp will send an ENTER_PIN message on error or message ENTER_CAN if the retryCounter of the card is decreased to 1. For detailed information see message ENTER_PIN.
If the PIN was correct, the workflow will continue.
If the last attempt to enter the PIN failed, AusweisApp will send the message ENTER_PUK as the retryCounter is decreased to 0.
Changed in version 1.16.0: The parameter “value” must be omitted if the used READER has a keypad.
value: The Personal Identification Number (PIN) of the card. This must be 6 digits in an AUTH workflow. If a CHANGE_PIN workflow is in progress the value must be 5 or 6 digits because of a possible transport PIN. If the READER has a keypad this parameter must be omitted.
{
"cmd": "SET_PIN",
"value": "123456"
}
SET_NEW_PIN
Set new PIN of inserted card.
If the AusweisApp sends message ENTER_NEW_PIN you need to send this command to set the new PIN of the card.
New in version 1.22.0: Support of SET_NEW_PIN command.
value: The new personal identification number (PIN) of the card. This must be 6 digits if the READER has no keypad, otherwise this parameter must be omitted.
{
"cmd": "SET_NEW_PIN",
"value": "123456"
}
Note
This command is allowed only if the AusweisApp sends an initial ENTER_NEW_PIN message. Otherwise you will get a BAD_STATE message as an answer.
SET_CAN
Set CAN of inserted card.
If the AusweisApp sends message ENTER_CAN you need to send this command to unblock the last retry of SET_PIN.
The AusweisApp will send an ENTER_CAN message on error. Otherwise the workflow will continue with ENTER_PIN.
Changed in version 1.16.0: The parameter “value” must be omitted if the used READER has a keypad.
value: The Card Access Number (CAN) of the card. This must be 6 digits if the READER has no keypad, otherwise this parameter must be omitted.
{
"cmd": "SET_CAN",
"value": "123456"
}
SET_PUK
Set PUK of inserted card.
If the AusweisApp sends message ENTER_PUK you need to send this command to unblock SET_PIN.
The AusweisApp will send an ENTER_PUK message on error or if the PUK is operative. Otherwise the workflow will continue with ENTER_PIN. For detailed information see message ENTER_PUK.
Changed in version 1.16.0: The parameter “value” must be omitted if the used READER has a keypad.
value: The Personal Unblocking Key (PUK) of the card. This must be 10 digits if the READER has no keypad, otherwise this parameter must be omitted.
{
"cmd": "SET_PUK",
"value": "1234567890"
}