Workflow
--------
This section shows some possible workflows as an example
communication between your application and the |AppName|.

The JSON structure can be identified by parameter **cmd**
or parameter **msg** as described in section :doc:`commands`
and section :doc:`messages`.

- **cmd**: Commands are sent by your application.

- **msg**: Messages are sent by the |AppName|.



Minimal successful authentication
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following messages and commands are the minimal
iterations of a successful authentication.

We assume that the user already inserted a card
into the connected card reader.


.. code-block:: json

  {"cmd": "RUN_AUTH", "tcTokenURL": "https://test.governikus-eid.de/Autent-DemoApplication/api/eid/request"}

  {"msg": "AUTH"}

  {"msg": "ACCESS_RIGHTS", "chat": {"effective":["FamilyName","GivenNames","DocumentType"],"optional":["GivenNames"],"required":["FamilyName","DocumentType"]}}

  {"cmd": "ACCEPT"}

  {"msg": "ENTER_PIN", "reader": {"attached":true,"card":{"inoperative":false,"deactivated":false,"retryCounter":3},"keypad":false,"name":"NFC"}}

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

  {"msg": "AUTH","result": {"major":"http://www.bsi.bund.de/ecard/api/1.1/resultmajor#ok"},"url":"https://test.governikus-eid.de/Autent-DemoApplication/refresh-address?sessionId=123456789&ResultMajor=ok"}



Successful authentication with CAN
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following messages and commands show possible
iterations if the user enters an incorrect PIN and CAN twice
before entering the correct CAN and PIN.

We assume that the user did not insert a card
into the connected card reader.


.. code-block:: json

  {"cmd": "RUN_AUTH", "tcTokenURL": "https://test.governikus-eid.de/DEMO"}

  {"msg": "AUTH"}

  {"msg": "ACCESS_RIGHTS", "chat": {"effective":["DocumentType"],"optional":[],"required":["DocumentType"]}}

  {"cmd": "ACCEPT"}

  {"msg": "INSERT_CARD"}

  {"msg": "ENTER_PIN", "reader": {"attached":true,"card":{"inoperative":false,"deactivated":false,"retryCounter":3},"keypad":false,"name":"NFC"}}

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

  {"msg": "ENTER_PIN", "reader": {"attached":true,"card":{"inoperative":false,"deactivated":false,"retryCounter":2},"keypad":false,"name":"NFC"}}

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

  {"msg": "ENTER_CAN", "reader": {"attached":true,"card":{"inoperative":false,"deactivated":false,"retryCounter":1},"keypad":false,"name":"NFC"}}

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

  {"msg": "ENTER_CAN", "reader": {"attached":true,"card":{"inoperative":false,"deactivated":false,"retryCounter":1},"keypad":false,"name":"NFC"}}

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

  {"msg": "ENTER_PIN", "reader": {"attached":true,"card":{"inoperative":false,"deactivated":false,"retryCounter":1},"keypad":false,"name":"NFC"}}

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

  {"msg": "AUTH","result": {"major":"http://www.bsi.bund.de/ecard/api/1.1/resultmajor#ok"},"url":"https://test.governikus-eid.de/DEMO/refresh-address?sessionId=123456789&ResultMajor=ok"}



Cancelled authentication
^^^^^^^^^^^^^^^^^^^^^^^^
The following messages and commands show possible
iterations if the user cancels the authentication.

We assume that the user did not connect the card reader.


.. code-block:: json

  {"cmd": "RUN_AUTH", "tcTokenURL": "https://test.governikus-eid.de/DEMO"}

  {"msg": "AUTH"}

  {"msg": "ACCESS_RIGHTS", "chat": {"effective":["DocumentType"],"optional":[],"required":["DocumentType"]}}

  {"cmd": "CANCEL"}

  {"msg": "AUTH", "result": {"description":"The process has been cancelled.","language":"en","major":"http://www.bsi.bund.de/ecard/api/1.1/resultmajor#error","message":"The process has been cancelled.","minor":"http://www.bsi.bund.de/ecard/api/1.1/resultminor/sal#cancellationByUser"},"url":"https://test.governikus-eid.de/DEMO/refresh-address?sessionId=123456789&ResultMajor=error&ResultMinor=cancellationByUser"}



Set some access rights
^^^^^^^^^^^^^^^^^^^^^^
The following messages and commands show possible
iterations if the user disables and enables an access right.

We assume that the user did not connect the card reader.


.. code-block:: json

  {"cmd": "RUN_AUTH", "tcTokenURL": "https://test.governikus-eid.de/DEMO"}

  {"msg": "AUTH"}

  {"msg": "ACCESS_RIGHTS", "chat": {"effective":["FamilyName","GivenNames","DocumentType"],"optional":["GivenNames"],"required":["FamilyName","DocumentType"]}}

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

  {"msg": "ACCESS_RIGHTS", "chat": {"effective":["FamilyName","DocumentType"],"optional":["GivenNames"],"required":["FamilyName","DocumentType"]}}

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

  {"msg": "ACCESS_RIGHTS", "chat": {"effective":["FamilyName","GivenNames","DocumentType"],"optional":["GivenNames"],"required":["FamilyName","DocumentType"]}}

  {"cmd": "CANCEL"}

  {"msg": "AUTH", "result": {"description":"The process has been cancelled.","language":"en","major":"http://www.bsi.bund.de/ecard/api/1.1/resultmajor#error","message":"The process has been cancelled.","minor":"http://www.bsi.bund.de/ecard/api/1.1/resultminor/sal#cancellationByUser"},"url":"https://test.governikus-eid.de/DEMO/refresh-address?sessionId=123456789&ResultMajor=error&ResultMinor=cancellationByUser"}



Minimal successful PIN change
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following messages and commands are the minimal
iterations of a successful PIN change.

We assume that the user already inserted a card
into the connected card reader.


.. code-block:: json

  {"cmd": "RUN_CHANGE_PIN"}

  {"msg": "CHANGE_PIN"}

  {"msg": "ENTER_PIN", "reader": {"attached":true,"card":{"inoperative":false,"deactivated":false,"retryCounter":3},"keypad":false,"name":"NFC"}}

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

  {"msg": "ENTER_NEW_PIN", "reader": {"attached":true,"card":{"inoperative":false,"deactivated":false,"retryCounter":3},"keypad":false,"name":"NFC"}}

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

  {"msg": "CHANGE_PIN", "success": true}
