Messages
The AusweisApp (server) will send some proper messages (msg) to your application (client) during the whole workflow or as an answer to your Commands.
ACCESS_RIGHTS
This message will be sent by AusweisApp once the authentication is started by RUN_AUTH and the AusweisApp got the certificate from the service.
If your application receives this message you can call SET_ACCESS_RIGHTS to change some optional access rights or you can call GET_ACCESS_RIGHTS to get this message again.
Also you can call GET_CERTIFICATE to get the certificate to show this to your user.
The workflow will continue if you call ACCEPT to indicate that the user accepted the requested access rights or call CANCEL to abort the whole workflow.
error: This optional parameter indicates an error of a SET_ACCESS_RIGHTS call if the command contained invalid data.
chat: Access rights of the provider.
effective: Indicates the enabled access rights of optional and required.
optional: These rights are optional and can be enabled or disabled by SET_ACCESS_RIGHTS.
required: These rights are mandatory and cannot be disabled.
transactionInfo: Optional transaction information.
aux: Optional auxiliary data of the provider.
ageVerificationDate: Optional required date of birth for AgeVerification as ISO 8601.
requiredAge: Optional required age for AgeVerification. It is calculated by AusweisApp on the basis of ageVerificationDate and current date.
validityDate: Optional validity date as ISO 8601.
communityId: Optional id of community.
{
"msg": "ACCESS_RIGHTS",
"error": "some optional error message",
"chat":
{
"effective": ["Address", "FamilyName", "GivenNames", "AgeVerification", "CanAllowed"],
"optional": ["GivenNames", "AgeVerification", "CanAllowed"],
"required": ["Address", "FamilyName"]
},
"transactionInfo": "this is an example",
"aux":
{
"ageVerificationDate": "1999-07-20",
"requiredAge": "18",
"validityDate": "2017-07-20",
"communityId": "02760400110000"
}
}
{
"msg": "ACCESS_RIGHTS",
"chat":
{
"effective": ["Address", "FamilyName", "GivenNames", "AgeVerification"],
"optional": ["GivenNames", "AgeVerification"],
"required": ["Address", "FamilyName"]
}
}
Values
New in version 1.22.0: The following access rights are possible now:
CanAllowed
PinManagement
New in version 1.20.0: The following write access rights are possible now:
WriteAddress
WriteCommunityID
WriteResidencePermitI
WriteResidencePermitII
The following access rights are possible:
Address
BirthName
FamilyName
GivenNames
PlaceOfBirth
DateOfBirth
DoctoralDegree
ArtisticName
Pseudonym
ValidUntil
Nationality
IssuingCountry
DocumentType
ResidencePermitI
ResidencePermitII
CommunityID
AddressVerification
AgeVerification
WriteAddress
WriteCommunityID
WriteResidencePermitI
WriteResidencePermitII
CanAllowed
PinManagement
API_LEVEL
This message will be sent if GET_API_LEVEL or SET_API_LEVEL is called.
It lists all available API levels that can be used and set by SET_API_LEVEL. Also it indicates the current selected API level.
New in version 1.24.0: Level 2 added.
error: Optional error message if SET_API_LEVEL failed.
available: List of supported API level by this version.
current: Currently selected API level.
{
"msg": "API_LEVEL",
"error": "optional error message like an invalid level",
"available": [1,2,3,4],
"current": 4
}
Your application should always set the compatible API level. The AusweisApp will support multiple API levels to give you enough time to add support for the new API.
Even if you added support for the new API, your application should still support the old API level in case the user updates your application but does not update the AusweisApp. Otherwise you need to show a message to the user that they need to update the AusweisApp.
The API level will be increased for incompatible changes only. If we can add additional commands, messages or information without breaking the previous API you can check the application version with GET_INFO to know if the current version supports your requirements.
This documentation will mark every API change with a flag like the following:
New in version 1.10.0.
Changed in version 1.10.0.
Deprecated since version 1.10.0.
AUTH
This message will be sent by AusweisApp if an authentication is initially started. The next message should be ACCESS_RIGHTS or AUTH again if the authentication immediately results in an error.
If you receive an AUTH message with a parameter error your command RUN_AUTH was invalid and the workflow was not started at all.
error: Optional error message if RUN_AUTH failed.
{
"msg": "AUTH",
"error": "error message if RUN_AUTH failed"
}
If the workflow is finished the AusweisApp will send a message with a result and an url parameter to indicate the end of an authentication.
New in version 1.26.3: Parameter reason added.
result: The final result of authentication.
major: Major “error” code.
minor: Minor error code.
language: Language of description and message. Language “en” is supported only at the moment.
description: Description of the error message.
message: The error message.
reason: Unique Failure Codes.
url: Refresh url or an optional communication error address.
{
"msg": "AUTH",
"result":
{
"major": "http://www.bsi.bund.de/ecard/api/1.1/resultmajor#ok"
},
"url": "https://test.governikus-eid.de/gov_autent/async?refID=_123456789"
}
{
"msg": "AUTH",
"result":
{
"major": "http://www.bsi.bund.de/ecard/api/1.1/resultmajor#error",
"minor": "http://www.bsi.bund.de/ecard/api/1.1/resultminor/al/common#internalError",
"language": "en",
"description": "An internal error has occurred during processing.",
"message": "The connection to the ID card has been lost. The process was aborted.",
"reason": "Card_Removed"
},
"url": "https://test.governikus-eid.de/gov_autent/async?refID=_abcdefgh"
}
BAD_STATE
Indicates that your previous command was send in an invalid state.
Some commands can be send to the server only if certain “state” is reached in the workflow to obtain the corresponding result. Otherwise the command will fail with BAD_STATE.
For example, you cannot send GET_CERTIFICATE if there is no authentication in progress.
error: Name of the received command that is invalid in this state.
{
"msg": "BAD_STATE",
"error": "NAME_OF_YOUR_COMMAND"
}
CERTIFICATE
Provides information about the used certificate.
description: Detailed description of the certificate.
issuerName: Name of the certificate issuer.
issuerUrl: URL of the certificate issuer.
subjectName: Name of the certificate subject.
subjectUrl: URL of the certificate subject.
termsOfUsage: Raw certificate information about the terms of usage.
purpose: Parsed purpose of the terms of usage.
validity: Validity dates of the certificate in UTC.
effectiveDate: Certificate is valid since this date.
expirationDate: Certificate is invalid after this date.
{
"msg": "CERTIFICATE",
"description":
{
"issuerName": "Governikus Test DVCA",
"issuerUrl": "http://www.governikus.de",
"subjectName": "Governikus GmbH & Co. KG",
"subjectUrl": "https://test.governikus-eid.de",
"termsOfUsage": "Anschrift:\t\r\nGovernikus GmbH & Co. KG\r\nAm Fallturm 9\r\n28359 Bremen\t\r\n\r\nE-Mail-Adresse:\thb@bos-bremen.de\t\r\n\r\nZweck des Auslesevorgangs:\tDemonstration des eID-Service\t\r\n\r\nZuständige Datenschutzaufsicht:\t\r\nDie Landesbeauftragte für Datenschutz und Informationsfreiheit der Freien Hansestadt Bremen\r\nArndtstraße 1\r\n27570 Bremerhaven",
"purpose": "Demonstration des eID-Service"
},
"validity":
{
"effectiveDate": "2016-07-31",
"expirationDate": "2016-08-30"
}
}
CHANGE_PIN
This message will be sent by AusweisApp if a change PIN workflow is initially started.
If you receive a CHANGE_PIN message with a parameter success the workflow is finished. This could happen after a SET_PIN command if the connection to the card failed. Also the parameter success is false after a CANCEL command.
New in version 1.22.0: Support of CHANGE_PIN message.
New in version 1.26.4: Parameter reason added.
success: Indicates with true that the PIN was successfully changed, otherwise false.
reason: Unique Failure Codes.
{
"msg": "CHANGE_PIN",
"success": true
}
{
"msg": "CHANGE_PIN",
"success": false,
"reason": "Card_Removed"
}
ENTER_CAN
Indicates that a CAN is required to continue workflow.
If the AusweisApp sends this message, you will have to provide the CAN of the inserted card with SET_CAN.
The CAN is required to enable the last attempt of PIN input if the retryCounter is 1. The workflow continues automatically with the correct CAN and the AusweisApp will send an ENTER_PIN message. Despite the correct CAN being entered, the retryCounter remains at 1.
The CAN is also required, if the authentication terminal has an approved “CAN allowed right”. This allows the workflow to continue without an additional PIN.
If your application provides an invalid SET_CAN command the AusweisApp will send an ENTER_CAN message with an error parameter.
If your application provides a valid SET_CAN command and the CAN was incorrect the AusweisApp will send ENTER_CAN again but without an error parameter.
New in version 1.14.2: Support of “CAN allowed right”.
{
"msg": "ENTER_CAN",
"error": "You must provide 6 digits",
"reader":
{
"name": "NFC",
"insertable": false,
"attached": true,
"keypad": false,
"card":
{
"inoperative": false,
"deactivated": false,
"retryCounter": 1
}
}
}
Note
There is no retry limit for an incorrect CAN.
ENTER_PIN
Indicates that a PIN is required to continue the workflow.
If the AusweisApp sends this message, you will have to provide the PIN of the inserted card with SET_PIN.
The workflow will automatically continue if the PIN was correct. Otherwise you will receive another message ENTER_PIN. If the correct PIN is entered the retryCounter will be set to 3.
If your application provides an invalid SET_PIN command the AusweisApp will send an ENTER_PIN message with an error parameter and the retryCounter of the card is not decreased.
If your application provides a valid SET_PIN command and the PIN was incorrect the AusweisApp will send ENTER_PIN again with a decreased retryCounter but without an error parameter.
If the value of retryCounter is 1 the AusweisApp will initially send an ENTER_CAN message. Once your application provides a correct CAN the AusweisApp will send an ENTER_PIN again with a retryCounter of 1.
If the value of retryCounter is 0 the AusweisApp will initially send an ENTER_PUK message. Once your application provides a correct PUK the AusweisApp will send an ENTER_PIN again with a retryCounter of 3.
{
"msg": "ENTER_PIN",
"error": "You must provide 6 digits",
"reader":
{
"name": "NFC",
"insertable": false,
"attached": true,
"keypad": false,
"card":
{
"inoperative": false,
"deactivated": false,
"retryCounter": 3
}
}
}
ENTER_NEW_PIN
Indicates that a new PIN is required to continue the workflow.
If the AusweisApp sends this message, you will have to provide the new PIN of the inserted card with SET_NEW_PIN.
New in version 1.22.0: Support of ENTER_NEW_PIN message.
error: Optional error message if your command SET_NEW_PIN was invalid.
reader: Information about the used card and card reader. Please see message READER for details.
{
"msg": "ENTER_NEW_PIN",
"error": "You must provide 6 digits",
"reader":
{
"name": "NFC",
"insertable": false,
"attached": true,
"keypad": false,
"card":
{
"inoperative": false,
"deactivated": false,
"retryCounter": 3
}
}
}
ENTER_PUK
Indicates that a PUK is required to continue the workflow.
If the AusweisApp sends this message, you will have to provide the PUK of the inserted card with SET_PUK.
The workflow will automatically continue if the PUK was correct and the AusweisApp will send an ENTER_PIN message. Otherwise you will receive another message ENTER_PUK. If the correct PUK is entered the retryCounter will be set to 3.
If your application provides an invalid SET_PUK command the AusweisApp will send an ENTER_PUK message with an error parameter.
If your application provides a valid SET_PUK command and the PUK was incorrect the AusweisApp will send ENTER_PUK again but without an error parameter.
If AusweisApp sends ENTER_PUK with field “inoperative” of embedded READER message set true it is not possible to unblock the PIN. You will have to show a message to the user that the card is inoperative and the user should contact the authority responsible for issuing the identification card to unblock the PIN. You need to send a CANCEL to abort the workflow if card is operative. Please see the note for more information.
{
"msg": "ENTER_PUK",
"error": "You must provide 10 digits",
"reader":
{
"name": "NFC",
"insertable": false,
"attached": true,
"keypad": false,
"card":
{
"inoperative": false,
"deactivated": false,
"retryCounter": 0
}
}
}
Note
There is no retry limit for an incorrect PUK. But be aware that the PUK can only be used 10 times to unblock the PIN. There is no readable counter for this. The AusweisApp is not able to provide any counter information of PUK usage. If the PUK is used 10 times it is not possible to unblock the PIN anymore and the card will remain in PUK state. Also it is not possible to indicate this state before the user enters the correct PUK once. This information will be provided as field “inoperative” of READER message.
INFO
Provides information about the AusweisApp.
Especially if you want to get a specific Implementation-Version to check if the current installation supports some additional Commands or Messages.
Also you should check the API_LEVEL as it will be increased for incompatible changes.
VersionInfo: Structure of version information.
Name: Application name.
Implementation-Title: Title of implementation.
Implementation-Vendor: Vendor of implementation.
Implementation-Version: Version of implementation.
Specification-Title: Title of specification.
Specification-Vendor: Vendor of specification.
Specification-Version: Version of specification.
{
"msg": "INFO",
"VersionInfo":
{
"Name": "AusweisApp2",
"Implementation-Title": "AusweisApp2",
"Implementation-Vendor": "Governikus GmbH & Co. KG",
"Implementation-Version": "2.0.0",
"Specification-Title": "TR-03124-1",
"Specification-Vendor": "Federal Office for Information Security",
"Specification-Version": "1.4"
}
}
INSERT_CARD
Indicates that the AusweisApp requires a card to continue.
If the AusweisApp needs a card to continue the workflow this message will be sent as a notification. If your application receives this message it should show a hint to the user.
The user must provide a physical card or your application needs to to provide a “virtual” card by calling SET_CARD.
After the user or your application inserted a card, the workflow will continue automatically, unless both the eID function and CAN allowed mode are disabled. CAN allowed mode is enabled if the AusweisApp is used as SDK and the certificate contains the CAN allowed right. In this case, the workflow will be paused until another card is inserted. If the user already inserted a card this message will not be sent at all.
This message will also be sent if there is no connected card reader.
error: Optional detailed error message.
{
"msg": "INSERT_CARD",
"error": "Name cannot be undefined"
}
INTERNAL_ERROR
Indicates an internal error.
If your application receives this message you found a bug. Please report this issue to our support!
error: Optional detailed error message.
{
"msg": "INTERNAL_ERROR",
"error": "Unexpected condition"
}
INVALID
Indicates a broken JSON message.
If your application receives this message you passed a broken JSON structure to the AusweisApp.
Please fix your JSON document and send it again!
error: Detailed error message.
{
"msg": "INVALID",
"error": "unterminated string (offset: 12)"
}
READER
Provides information about a connected or disconnected card reader.
This message will be sent by the AusweisApp if a card reader was added or removed to the operating system. Also if a card was inserted into a card reader or removed from a card reader.
Your application can explicitly check for card reader with GET_READER.
If a workflow is in progress and a card with disabled eID function was inserted, this message will still be sent, but the workflow will be paused until a card with enabled eID function is inserted.
New in version 2.2.0: Parameter card signals an unknown card with an empty object (API_LEVEL 3).
New in version 1.24.0: Parameter insertable added.
New in version 1.16.0: Parameter keypad added.
name: Identifier of card reader.
insertable: Indicates whether a card can be inserted via SET_CARD.
attached: Indicates whether a card reader is connected or disconnected.
keypad: Indicates whether a card reader has a keypad. The parameter is only shown when a reader is attached.
card: Provides information about an inserted eID card. An empty object is used for an unknown card. Otherwise null.
inoperative: True if PUK is inoperative and cannot unblock PIN, otherwise false. This can be recognized if user enters a correct PUK only. It is not possbible to read this data before a user tries to unblock the PIN.
deactivated: True if eID function is deactivated, otherwise false. The scan dialog on iOS won’t be closed if this is True. You need to send INTERRUPT yourself to show an error message.
retryCounter: Count of possible retries for the PIN. If you enter a PIN with command SET_PIN it will be decreased if PIN was incorrect.
eID card:
{
"msg": "READER",
"name": "NFC",
"insertable": false,
"attached": true,
"keypad": false,
"card":
{
"inoperative": false,
"deactivated": false,
"retryCounter": 3
}
}
Unknown card (API_LEVEL 3):
{
"msg": "READER",
"name": "NFC",
"insertable": false,
"attached": true,
"keypad": false,
"card": {}
}
No card:
{
"msg": "READER",
"name": "NFC",
"insertable": false,
"attached": true,
"keypad": false,
"card": null
}
READER_LIST
Provides information about all connected card readers.
Changed in version 1.24.0: Parameter reader was renamed to readers with API_LEVEL 2.
readers: A list of all connected card readers. Please see message READER for details.
{
"msg": "READER_LIST",
"readers":
[
{
"name": "Example reader 1 [SmartCard] (1234567) 01 00",
"insertable": false,
"attached": true,
"keypad": true,
"card": null
},
{
"name": "NFC",
"insertable": false,
"attached": true,
"keypad": false,
"card":
{
"inoperative": false,
"deactivated": false,
"retryCounter": 3
}
}
]
}
STATUS
Provides information about the current workflow and state. This message indicates if a workflow is in progress or the workflow is paused. This can occur if the AusweisApp needs additional data like ACCESS_RIGHTS or INSERT_CARD.
The messages will be sent by default if not disabled in RUN_AUTH or RUN_CHANGE_PIN.
New in version 1.24.0: Support of STATUS message in API_LEVEL 2.
workflow: Name of the current workflow. If there is no workflow in progress this will be null.
progress: Percentage of workflow progress. If there is no workflow in progress this will be null.
state: Name of the current state if paused. If there is no workflow in progress or the workflow is not paused this will be null.
{
"msg": "STATUS",
"workflow": "AUTH",
"progress": 25,
"state": "ACCESS_RIGHTS"
}
PAUSE
This message will be sent by AusweisApp to signal certain waiting conditions. E.g. if a card connection cannot be established or maintained due to a bad positioning of the card, this message will be send with BadCardPosition as the cause. After the causing issue, denoted be the value of cause, was fixed, the next command should be CONTINUE.
New in version 2.2.0: The message PAUSE was introduced in API_LEVEL 3. The SDK will halt until CONTINUE was sent to acknowledge the condition.
cause: The cause for the waiting condition.
{
"msg": "PAUSE",
"cause": "BadCardPosition"
}
The following list of causes contains all conditions. Each condition is a stable and unique string to safely distinguish each waiting condition.
BadCardPosition: Denotes an unstable or lost card connection. After fixing the issue you have to call CONTINUE to go on with the workflow.
UNKNOWN_COMMAND
Indicates that the command type is unknown.
If your application receives this message you passed a wrong command to the AusweisApp.
Please fix your command and send it again!
Be aware of case sensitive names in Commands.
error: Name of the unknown command.
{
"msg": "UNKNOWN_COMMAND",
"error": "get_INFo"
}