Commands
--------
Your application (client) can send some commands (**cmd**) to
control the AusweisApp2. The AusweisApp2 (server) will send
some proper :doc:`messages` during the whole workflow or as an
answer to your command.




.. _get_info:

GET_INFO
^^^^^^^^
Returns information about the current installation of AusweisApp2.

The AusweisApp2 will send an :ref:`info` message as an answer.


.. code-block:: json

  {"cmd": "GET_INFO"}




.. _get_api_level:

GET_API_LEVEL
^^^^^^^^^^^^^
Returns information about the available and current API level.

The AusweisApp2 will send an :ref:`api_level` message as an answer.


.. code-block:: json

  {"cmd": "GET_API_LEVEL"}




.. _set_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 :ref:`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 :ref:`api_level` message as an answer.


  - **level**:
    Supported API level of your app.

.. code-block:: json

  {
    "cmd": "SET_API_LEVEL",
    "level": 1
  }




.. _get_reader:

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 :ref:`reader` message as an answer.


  - **name**:
    Name of the reader.

.. code-block:: json

  {
    "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 :ref:`reader_list` message as an answer.


.. code-block:: json

  {"cmd": "GET_READER_LIST"}




.. _run_auth:

RUN_AUTH
^^^^^^^^
Starts an authentication.

The AusweisApp2 will send an :ref:`auth` message when the authentication is started.

The system dialog on iOS can be customized by **handleInterrupt** and **messages**.
This dialog will be stopped by default (true) after an :ref:`enter_pin`, :ref:`enter_can`
and :ref:`enter_puk`. You can disable that behavior with
**handleInterrupt**. Command :ref:`interrupt` allows to stop the dialog manually,
if needed.


.. versionadded:: 1.22.3
   Parameter **developerMode** added.

.. versionadded:: 1.22.1
   Parameter **handleInterrupt** and **messages** added.

.. deprecated:: 1.22.1
   Parameter **handleInterrupt** will be removed with :ref:`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 according to BSI TR-03124-1,
    otherwise false.

  - **handleInterrupt**: True to automatically handle system dialog on iOS, otherwise false.

  - **messages**: Optional messages for the system dialog on iOS.

    - **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.

.. code-block:: json

  {
    "cmd": "RUN_AUTH",
    "tcTokenURL": "https://test.governikus-eid.de/Autent-DemoApplication/RequestServlet?provider=demo_epa_20&redirect=true",
    "developerMode": false,
    "handleInterrupt": 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 AusweisApp2 has no running
  authentication or other workflow. Otherwise you will get
  a :ref:`bad_state` message as an answer.




.. _run_change_pin:

RUN_CHANGE_PIN
^^^^^^^^^^^^^^
Starts a change PIN workflow.

The AusweisApp2 will send a :ref:`change_pin` message when the workflow is started.

The system dialog on iOS can be customized by **handleInterrupt** and **messages**.
This dialog will be stopped by default (true) after an :ref:`enter_pin`, :ref:`enter_can`,
:ref:`enter_new_pin` and :ref:`enter_puk`. You can disable that behavior with parameter
**handleInterrupt**. Command :ref:`interrupt` allows to stop the dialog manually, if needed.


.. versionadded:: 1.22.0
   Support of RUN_CHANGE_PIN command.

.. versionadded:: 1.22.1
   Parameter **handleInterrupt** and **messages** added.

.. deprecated:: 1.22.1
   Parameter **handleInterrupt** will be removed with :ref:`api_level` v2
   and defaults to ``false``.


  - **handleInterrupt**: True to automatically handle system dialog on iOS, otherwise false.

  - **messages**: Optional messages for the system dialog on iOS.

    - **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.

.. code-block:: json

  {
    "cmd": "RUN_CHANGE_PIN",
    "handleInterrupt": 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 AusweisApp2 has no running
  authentication or other workflow. Otherwise you will get
  a :ref:`bad_state` message as an answer.




.. _get_access_rights:

GET_ACCESS_RIGHTS
^^^^^^^^^^^^^^^^^
Returns information about the requested access rights.

The AusweisApp2 will send an :ref:`access_rights` message as an answer.


.. code-block:: json

  {"cmd": "GET_ACCESS_RIGHTS"}

.. note::
  This command is allowed only if the AusweisApp2 sends an initial
  :ref:`access_rights` message. Otherwise you will get a :ref:`bad_state`
  message as an answer.




.. _set_access_rights:

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 :ref:`access_rights` message as an answer.


  - **chat**:
    List of enabled **optional** access rights. If you send an empty **[]**
    all **optional** access rights are disabled.

.. code-block:: json

  {
    "cmd": "SET_ACCESS_RIGHTS",
    "chat": []
  }

.. code-block:: json

  {
    "cmd": "SET_ACCESS_RIGHTS",
    "chat": ["FamilyName"]
  }

.. note::
  This command is allowed only if the AusweisApp2 sends an initial
  :ref:`access_rights` message. Otherwise you will get a :ref:`bad_state`
  message as an answer.

.. seealso::
  List of possible access rights are listed in :ref:`access_rights`.



.. _get_certificate:

GET_CERTIFICATE
^^^^^^^^^^^^^^^
Returns the certificate of current authentication.

The AusweisApp2 will send a :ref:`certificate` message as an answer.


.. code-block:: json

  {"cmd": "GET_CERTIFICATE"}

.. note::
  This command is allowed only if the AusweisApp2 sends an initial
  :ref:`access_rights` message. Otherwise you will get a :ref:`bad_state`
  message as an answer.




.. _cancel:

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.


.. code-block:: json

  {"cmd": "CANCEL"}

.. note::
  This command is allowed only if the AusweisApp2 started an authentication or
  the :ref:`change_pin` workflow.
  Otherwise you will get a :ref:`bad_state` message as an answer.




.. _accept:

ACCEPT
^^^^^^
Accept the current state.

If the AusweisApp2 will send the message :ref:`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 :ref:`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 :ref:`api_level` v1
only :ref:`access_rights` needs to be accepted.


.. code-block:: json

  {"cmd": "ACCEPT"}

.. note::
  This command is allowed only if the AusweisApp2 sends an initial
  :ref:`access_rights` message. Otherwise you will get a :ref:`bad_state`
  message as an answer.




.. _interrupt:

INTERRUPT
^^^^^^^^^
Interrupts current system dialog on iOS.

If your application provides **false** to parameter **handleInterrupt** in
:ref:`run_auth` or :ref:`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.

.. versionadded:: 1.22.1
   Support of INTERRUPT command.


.. code-block:: json

  {"cmd": "INTERRUPT"}

.. note::
  This command is allowed only if the AusweisApp2 sends a :ref:`enter_pin`,
  :ref:`enter_can`, :ref:`enter_new_pin` or :ref:`enter_puk` message.
  Otherwise you will get a :ref:`bad_state` message as an answer.




.. _set_pin:

SET_PIN
^^^^^^^
Set PIN of inserted card.

If the AusweisApp2 sends message :ref:`enter_pin` you need
to send this command to unblock the card with the PIN.

The AusweisApp2 will send an :ref:`enter_pin` message on error
or message :ref:`enter_can` if the retryCounter of the card
is decreased to **1**.
For detailed information see message :ref:`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 :ref:`enter_puk` as the retryCounter
is decreased to **0**.

.. versionchanged:: 1.16.0
   The parameter "value" must be omitted if the used :ref:`reader` has a
   keypad.


- **value**: The Personal Identification Number (PIN) of the card.
  This must be 6 digits in an :ref:`auth` workflow. If a
  :ref:`change_pin` workflow is in progress the value must
  be 5 or 6 digits because of a possible transport PIN.
  If the :ref:`reader` has a keypad this parameter must be omitted.

.. code-block:: json

  {
    "cmd": "SET_PIN",
    "value": "123456"
  }

.. note::
  This command is allowed only if the AusweisApp2 sends an initial
  :ref:`enter_pin` message. Otherwise you will get a :ref:`bad_state`
  message as an answer.




.. _set_new_pin:

SET_NEW_PIN
^^^^^^^^^^^
Set new PIN of inserted card.

If the AusweisApp2 sends message :ref:`enter_new_pin` you need
to send this command to set the new PIN of the card.

.. versionadded:: 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 :ref:`reader` has no keypad, otherwise
  this parameter must be omitted.

.. code-block:: json

  {
    "cmd": "SET_NEW_PIN",
    "value": "123456"
  }

.. note::
  This command is allowed only if the AusweisApp2 sends an initial
  :ref:`enter_new_pin` message. Otherwise you will get a :ref:`bad_state`
  message as an answer.




.. _set_can:

SET_CAN
^^^^^^^
Set CAN of inserted card.

If the AusweisApp2 sends message :ref:`enter_can` you need
to send this command to unblock the last retry of :ref:`set_pin`.

The AusweisApp2 will send an :ref:`enter_can` message on error.
Otherwise the workflow will continue with :ref:`enter_pin`.

.. versionchanged:: 1.16.0
   The parameter "value" must be omitted if the used :ref:`reader` has a
   keypad.


- **value**: The Card Access Number (CAN) of the card.
  This must be 6 digits if the :ref:`reader` has no keypad, otherwise
  this parameter must be omitted.

.. code-block:: json

  {
    "cmd": "SET_CAN",
    "value": "123456"
  }

.. note::
  This command is allowed only if the AusweisApp2 sends an initial
  :ref:`enter_can` message. Otherwise you will get a :ref:`bad_state`
  message as an answer.




.. _set_puk:

SET_PUK
^^^^^^^
Set PUK of inserted card.

If the AusweisApp2 sends message :ref:`enter_puk` you need
to send this command to unblock :ref:`set_pin`.

The AusweisApp2 will send an :ref:`enter_puk` message on error
or if the PUK is operative.
Otherwise the workflow will continue with :ref:`enter_pin`.
For detailed information see message :ref:`enter_puk`.

.. versionchanged:: 1.16.0
   The parameter "value" must be omitted if the used :ref:`reader` has a
   keypad.


- **value**: The Personal Unblocking Key (PUK) of the card.
  This must be 10 digits if the :ref:`reader` has no keypad, otherwise
  this parameter must be omitted.

.. code-block:: json

  {
    "cmd": "SET_PUK",
    "value": "1234567890"
  }

.. note::
  This command is allowed only if the AusweisApp2 sends an initial
  :ref:`enter_puk` message. Otherwise you will get a :ref:`bad_state`
  message as an answer.
