Commands

Your application (client) can send some commands (cmd) to control the AusweisApp2. The AusweisApp2 (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 AusweisApp2.

The AusweisApp2 will send an INFO message as an answer.

{"cmd": "GET_INFO"}

GET_API_LEVEL

Returns information about the available and current API level.

The AusweisApp2 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 AusweisApp2 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 AusweisApp2 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 AusweisApp2 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 AusweisApp2 will send a READER_LIST message as an answer.

{"cmd": "GET_READER_LIST"}

RUN_AUTH

Starts an authentication.

The AusweisApp2 will send an AUTH message when the authentication is started.

  • tcTokenURL: URL to the TcToken. This is equal to the desktop style activation URL. (http://127.0.0.1:24727/eID-Client?tcTokenURL=)
{
  "cmd": "RUN_AUTH",
  "tcTokenURL": "https://test.governikus-eid.de/Autent-DemoApplication/RequestServlet?provider=demo_epa_20&redirect=true"
}

Note

This command is allowed only if the AusweisApp2 has no running authentication. Otherwise you will get a BAD_STATE message as an answer.

GET_ACCESS_RIGHTS

Returns information about the requested access rights.

The AusweisApp2 will send an ACCESS_RIGHTS message as an answer.

{"cmd": "GET_ACCESS_RIGHTS"}

Note

This command is allowed only if the AusweisApp2 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 AusweisApp2 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 AusweisApp2 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.

GET_CERTIFICATE

Returns the certificate of current authentication.

The AusweisApp2 will send a CERTIFICATE message as an answer.

{"cmd": "GET_CERTIFICATE"}

Note

This command is allowed only if the AusweisApp2 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 AusweisApp2 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 AusweisApp2 started an authentication. Otherwise you will get a BAD_STATE message as an answer.

ACCEPT

Accept the current state.

If the AusweisApp2 will send the message ACCESS_RIGHTS the user needs to accept or deny. 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 AusweisApp2 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 AusweisApp2 sends an initial ACCESS_RIGHTS message. Otherwise you will get a BAD_STATE message as an answer.

SET_PIN

Set PIN of inserted card.

If the AusweisApp2 sends message ENTER_PIN you need to send this command to unblock the card with the PIN.

The AusweisApp2 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, AusweisApp2 will send the message ENTER_PUK as the retryCounter is decreased to 0.

  • value: The personal identification number (PIN) of the card. This must be 6 digits.
{
  "cmd": "SET_PIN",
  "value": "123456"
}

Note

This command is allowed only if the AusweisApp2 sends an initial ENTER_PIN message. Otherwise you will get a BAD_STATE message as an answer.

SET_CAN

Set CAN of inserted card.

If the AusweisApp2 sends message ENTER_CAN you need to send this command to unblock the last retry of SET_PIN.

The AusweisApp2 will send an ENTER_CAN message on error. Otherwise the workflow will continue with ENTER_PIN.

  • value: The card access number (CAN) of the card. This must be 6 digits.
{
  "cmd": "SET_CAN",
  "value": "123456"
}

Note

This command is allowed only if the AusweisApp2 sends an initial ENTER_CAN message. Otherwise you will get a BAD_STATE message as an answer.

SET_PUK

Set PUK of inserted card.

If the AusweisApp2 sends message ENTER_PUK you need to send this command to unblock SET_PIN.

The AusweisApp2 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.

  • value: The personal unblocking key (PUK) of the card. This must be 10 digits.
{
  "cmd": "SET_PUK",
  "value": "1234567890"
}

Note

This command is allowed only if the AusweisApp2 sends an initial ENTER_PUK message. Otherwise you will get a BAD_STATE message as an answer.