Best Practices

This page provides guidelines for constructing requests, validating responses, and handling errors when integrating with the Mobile ID API.

Java Reference Client

For Java projects, use the official Java Reference Client — a production-ready library that implements all of these best practices out of the box.

MSS Signature

Signature Request

When constructing an MSS Signature request, the following best-practice guidelines should be followed:

Define a unique AP_TransID (Transaction ID) Each signature request must have a unique transaction identifier.
Set the current time for Instant (with time zone) The Instant parameter must include time zone information and must not deviate excessively from the Mobile ID Service's current time; otherwise, a fault response with sub-code 101 will be returned.
- Example: 2020-01-01T12:00:00.000+01:00
- Must conform to the W3C xs:dateTime format.
Ensure uniqueness across the triplet (AP_ID, AP_TransID, Instant) The combination of these three fields must be unique for every transaction. Duplicate triplets are rejected.
Specify MSISDN in international format The user's phone number must follow international (E.164) notation without spaces. A leading “+” is allowed but optional.
- Example: +41791234567
Set a valid UserLang value The value must be one of the supported languages — EN, DE, FR, or IT — and must match the language used in the DataToBeDisplayed (DTBD) message.
Define the DataToBeDisplayed (DTBD) message The text shown on the user’s mobile device must comply with the following guidelines:
- Encoded in UTF-8 ¹⁷.
- Should include a unique transaction reference (e.g., timestamp, customer ID, contract ID).
- Length limits:
  - Maximum 239 characters if all characters are in the standard GSM 03.38 character set.
  - If any character falls outside this set (e.g., the lowercase cedilla "ç"), the maximum length reduces to 119 characters.
- Keep the message as short and user-friendly as possible.
Example DTBD:
Bank ACME: Proceed with the login? (TXN-3D5K)

Footnotes

Type of the AP_TransID is xsd:NCName, refer to http://www.datypic.com/sc/xsd/t-xsd_NCName.html ↩
http://www.w3.org/TR/xmlschema-2/#dateTime ↩
http://en.wikipedia.org/wiki/UTF-8 ↩
In mobile telephony GSM 03.38 is the standard character set used in short message service. ↩

Signature Response

After receiving the MSS Signature Response, the client (Application Provider – AP) must perform proper response validation to ensure authenticity, integrity, and consistency with the original request.

The key validation aspects are as follows:

Match Request and Response Identifiers
- Verify that the AP_TransID and MSISDN values in the response are identical to those sent in the original request.
- Any mismatch should be treated as an invalid response and rejected.
Validate the Mobile User’s X.509 Certificate
- Ensure the user certificate chains up to a trusted root CA contained in your local TrustStore.
- The client should only trust certificates that link to a trust anchor matching the expected Swisscom Mobile ID CA.
- Your TrustStore should only contain the relevant root CA certificate (see Root CA Certificates).
Verify the Digital Signature
- Confirm that the received digital signature is cryptographically valid.
- The signed content must correspond exactly to the DataToBeDisplayed (DTBD) text from the earlier signature request.
- The client must be capable of validating both RSA and ECDSA signatures.
(Optional) Validate the Mobile ID Serial Number
- For the highest level of assurance and a fully strong two-factor authentication process, validate the Mobile ID serial number as described in Section Mobile ID Serial Number Validation.
Implement Proper Fault and Status Handling
- Handle all status and fault codes using structured exception handling logic to ensure stable, predictable behavior of the client application.

Important

Certificate revocation checks are not recommended. Mobile ID user certificates are never revoked individually — the Mobile ID service backend manages account validity and state directly.

Signature Concurrency Control

This section describes the behavior of the Mobile ID Service when an Application Provider (AP) submits a new MSS Signature request while another signature transaction is already in progress for the same MSISDN and the same authentication method.

Concurrency handling depends on whether the request targets the SIM method or the Mobile ID App method.

SIM Method Concurrency

If both signature requests target the SIM-based authentication method, and the first signature transaction is still in progress, the second request is rejected immediately.

Fault Code: 406 / PB_SIGNATURE_PROCESS
Description: The subscriber already has an active signature operation in process.
See Section 6 for detailed fault code definitions.

App Method Concurrency

If both requests target the Mobile ID App-based authentication method, the behavior is different:

The existing first signature transaction is canceled automatically by the backend.
The second signature request is then displayed on the mobile device via the Mobile ID App.
Fault Code (cancellation of first transaction): 401 / USER_CANCEL
See Section 6 for further information.

Serial Number Validation

With an MSS Signature response, you will get signature data and the mobile user's X.509 certificate, which contains the public key required to validate the signature data.

That X.509 certificate's Subject Name (Distinguished Name) contains a unique Mobile ID serial number.

Example subject name with the serial number:

bash


cn=midcheptod58qe59:pn,serialnumber=midcheptod58qe59,pseudonym=midcheptod58qe59

For highest level of assurance and a truly strong two-factor-authentication process, an AP should store this value at the first signature and then verify every subsequent signature response if that serial number value still matches.

WARNING

If the value does not match anymore, it means that the user re-activated their account without a valid recovery option. In such case (serial number mismatch) the 2nd factor (knowledge/inherence) is not assured.

Timeout Value

Recommended Timeout Values

Use the reference values below to set an appropriate transaction timeout:

MSS Operation	Transaction Timeout	Client Connection Timeout
Synchronous MSS Signature	80 seconds for Mobile ID SIM 40 seconds for Mobile ID App	90 seconds 50 seconds
Asynchronous MSS Signature	80 seconds for Mobile ID SIM 40 seconds for Mobile ID App	10 seconds
MSS Status Query	-	10 seconds
MSS Receipt	-	90 seconds
MSS Profile Query	-	10 seconds

Mobile ID FAQ

Please visit https://mobileid.ch/en/faq for a list of frequently asked questions about Mobile ID

Mobile ID Service Health Check

The recommended way to check the service health status is to send a synchronous MSS Signature request with the MSISDN value set to +41000000000 and DTBD set to Heartbeat.

The Mobile ID service health check is successful if a fault code 101/WRONG_PARAM with Detail value Illegal msisdn is returned, as shown in the example:

SOAP/XML

xml

..
      <soapenv:Fault>
         <soapenv:Code>
            <soapenv:Value>soapenv:Sender</soapenv:Value>
            <soapenv:Subcode xmlns:mss="http://uri.etsi.org/TS102204/v1.1.2#"
                             xmlns:fi="http://mss.ficom.fi/TS102204/v1.0.0#">
               <soapenv:Value>mss:_101</soapenv:Value>
            </soapenv:Subcode>
         </soapenv:Code>
         <soapenv:Reason>
            <soapenv:Text xml:lang="en">WRONG_PARAM</soapenv:Text>
         </soapenv:Reason>
         <soapenv:Detail>
            <ns1:detail xmlns:ns1="http://kiuru.methics.fi/mssp">Illegal msisdn</ns1:detail>
         </soapenv:Detail>
      </soapenv:Fault>
..

REST/JSON

json

..

{
    "Fault": {
        "Code": {
            "SubCode": {
                "Value": "_101",
                "ValueNs": "http://uri.etsi.org/TS102204/v1.1.2#"
            },
            "Value": "Sender",
            "ValueNs": "http://www.w3.org/2003/05/soap-envelope"
        },
        "Detail": "Illegal msisdn",
        "Reason": "WRONG_PARAM"
    }
}

..

Client Libraries

The MobileID-Strong-Authentication GitHub organisation provides reference implementations and examples for building Mobile ID clients.

Library	Language	Description
mobileid-client-java	Java 8+	Official reference implementation for REST and SOAP APIs

See the Java Reference Client page for setup instructions, code examples, and usage patterns.

Best Practices ​

MSS Signature ​

Signature Request ​

Signature Response ​

Signature Concurrency Control ​

SIM Method Concurrency ​

App Method Concurrency ​

Serial Number Validation ​

Timeout Value ​

Mobile ID FAQ ​

Mobile ID Service Health Check ​

SOAP/XML ​

REST/JSON ​

Client Libraries ​