Signicat's MobileID API offers a simple way to implement strong customer authentication on mobile devices.

The MobileID API is a RESTful API that uses the OAuth 2.0 protocol for authorisation. All request and response bodies are formatted in JSON.

To use our MobileID API, you need to complete the following steps:

1. If you do not have an account already, then you need to sign up to Signicat.

2. In the Signicat Dashboard, you must create an organisation and create an account.

Note: It is also possible to add a domain, but this is not required for MobileID.

3. To authenticate against our APIs, you need to set up an API client. From this step, you will obtain a Client ID and a Client Secret.

4. To use MobileID, you need to set the required permissions. Ensure that you select both MobileID API and MobileID Admin API as permissions.

You need to complete the onboarding of your account for MobileID. To do this, you can either:

Use the Signicat Dashboard

1. Log in to the Signicat Dashboard.

2. In the top navigation bar, use the dropdown menu next to your organisation name to select the account that you want to use MobileID on.

3. In the left-side menu, select MobileID.

4. Click the Create account button.

Use our MobileID Admin REST API

Make a request to the Add MobileID account endpoint in our MobileID Admin API.

Result of the onboarding

As a result of the onboarding, an account is added to the MobileID service. For each MobileID account, we will create an application configuration and an E2E key.

• The application configuration is identified by an applicationId, and contains specific settings for you app. You can see all of the configurable properties in our application configuration feature documentation.

• The E2E key is used to end-to-end encryption of all communication between our MobileID SDK and our service.

To configure the Authenticator App and the mobile SDK, you need the following:

• Application ID (applicationId)

• Public E2E key (publicKey)

• Server URL (https://api.signicat.com/encore/encap)

Note: Our server URL is the same for both sandbox and production accounts.

To get your Application ID (applicationId) and Public E2E key (publicKey), you can either:

Use the Signicat Dashboard

1. Log in to the Signicat Dashboard.

2. In the top navigation bar, use the dropdown menu next to your organisation name to select the account that you have onboarded to MobileID.

3. In the left-side menu, select MobileID.

4. Use the tabs for Account and E2E keys to see your Application ID and Public key.

Use our MobileID Admin REST API

• Make a request to the Get MobileID account endpoint in our MobileID Admin API to fetch your applicationId.

• Make a request to the Get E2E keys endpoint in our MobileID Admin API to fetch your publicKey.

1. For the MobileID account, you will be able to create users.

2. Each user can register one or more devices.

3. The devices can then be used to perform authentication and authorisation operations.

This API uses OAuth 2.0 for authorisation. OAuth 2.0 is an open protocol to allow secure authorisation in a simple and standardised manner.

For more information on how to access the MobileID API, see the Accessing Signicat API products guide in our developer documentation.

Callback enables you to receive the result of a completed operation automatically from Signicat, at a specified notification URI.

• To receive callback for MobileID events, you must subscribe to them using the Events service in the Signicat Dashboard.

• You will automatically receive the operation results for the events that your account has subscribed to.

• The operation result that you receive through callback is the same as the result obtained by polling, but wrapped in a callback event object. It is passed in the eventData field.

For more information about events and how to use the events service, see our Events and webhooks documentation.

When to use callback

We strongly advise that you always set up callback for production. This offers the best usability and responsiveness through reduced latency, and means that you do not need to conduct additional polling calls.

Regardless of whether callback is set up or not, you can fetch the result of a completed operation from Signicat by polling. You can do this by running get<resource> API calls, but it should only be reserved for testing and development use.

What events can I subscribe to?

You can see the full list of supported MobileID event types when you create a new subscription in the Signicat Dashboard.

To find out how to see this, see our documentation on Event types.

Set up callback

To set up callback for MobileID events, you need to:

1. Get started with the Events service.

2. Add a subscription for the MobileID events that you would like to receive callback for.

Now, when an operation is complete, Signicat's callback framework will send the callback event object to your configured notification URI if you are subscribed to that event.

MobileID returns an error object to you as a response when an error occurs. You can cross-reference the details provided in the error object with the table of error IDs below. From this, you can determine how to diagnose and resolve the error.

Note: Some of the errors illustrated are 'Generic errors', and can describe a number of possible issues. If you require support, you can contact us at support@signicat.com.

Error object

For MobileID, the error object can be made up from the following 7 fields:

Example 1: Response with error object

An example response with error object from MobileID:

{
    "type": "https://api.signicat.com/mobileid/core/openapi.json",
    "title": "User entity does not exist",
    "code": "user_entity_does_not_exist",
    "status": 404,
    "traceId": "4bf239c088089f2bca77d3a413909f1d",
    "detail": "Failed fetching user with user ID : 90e1b3e5-93a7-458e-b42b-d1b57e65e26a and account ID : a-sdge-Abcdefghijk123456789."
}

In this example, we can determine that the user entity (referred to by the userId in the request) does not exist.

The detail describes which user ID and account ID this refers to, so that you can take action accordingly.

Example 2: Response with error object

An example response with error object from MobileID, containing multiple invalid request parameters:

{
    "type": "https://api.signicat.com/mobileid/core/openapi.json",
    "title": "Invalid request parameter",
    "code": "invalid_request_parameter",
    "status": 400,
    "traceId": "4bf239c088089f2bca77d3a413909f1d",
    "detail": "Your request body parameters have failed validation."
    "invalidParams": [
        {
            "name": "userId"
            "reason": "userId cannot be null or empty"
        },
        {
            "name": "deviceId"
            "reason": "deviceId cannot be null or empty"
        }
    ]
}

In this example, we can determine that multiple request parameters have failed the validation.

The invalidParams describes which request parameters have failed the validation, so that you can modify them to pass the validation.

Error IDs

All MobileID responses set the following headers:

Possible values to use for the authentication level.

Possible values to use for the authentication method.

Note: Android deprecated fingerprint in Android 9, which was released in 2018. We have now also deprecated this method (DEVICE_ANDROID_FINGERPRINT), and it will be removed in an upcoming release.

Please use DEVICE_ANDROID_BIOMETRIC_PROMPT for biometric authentications on Android.

Possible values for the geofencing clientStatus field.

Possible values for the geofencing serverBoundaryValidation field.

Possible values for the hwKeyClientStatus attribute.

Possible values for the hwKeyServerResult attribute.

The maximum character length that the operation context content (content) can be for the different MobileID operations.

The state of the operation. The state and the values that are returned in the response depend on the API call you are executing.

The status of the passport scan.

Play Integrity attestation status for the device.

The risk attributes that can be collected for the device.

You can configure which attributes are collected in the application configuration.

• Risk attributes marked with Yes in the Always configured column are always collected, for debugging purposes.

• Risk attributes marked with No in the Always configured column are only collected if configured in the application configuration.

  Risk attribute	Type	Description	Always collected
  operationSystemFingerprint	String	A fingerprint of the operating system. You can use this to detect whether the device is running a custom ROM or operating system.	Yes
  operatingSystemVersion	String	The operating system version. Examples: 4.1.2, 6.0.1	Yes
  inputMethod	String	The input method that was used to enter text in the application. You can use this to detect when a custom keyboard is being used on the device. You can find more information about input methods in the Android developer documentation.	No
  isDebuggable	Boolean	Indicates whether the application running can be debugged using a source-level debugger, either by manifest entry or in emulator.	No
  isDebugEnabled	Boolean	Indicates whether debug is enabled on the device, either by user setting (USB-debugging enabled) or when running in emulator (debugging enabled by default).	No
  isDebuggerConnected	Boolean	Indicates whether a debugger is connected to the application.	No
  isEmulator	Boolean	Indicates whether the application is running in an emulator.	No
  isRootAvailable	Boolean	Indicates whether the device has been rooted/jail-broken. For iOS, this value has to be passed to Encap using the setRiskParameter API. If the application is using Shield, the callback value can be passed to Encap.	No
  isSecureScreenLockEnabled	Boolean	Indicates whether the device has secure screen enabled or not.	No
  isUnknownSourcesEnabled	Boolean	Indicates whether the device allows installation of applications outside of the application store.	No
  serverClientIp	String	The host address that the request originated from. It will contain the value of X-Forwarded-For (XFF) header from the request, and can contain multiple IP addresses depending on proxy and load balancers. If XFF is not present, we will use the remote address of the request. It can be either the IP of the client or the last proxy that sent the request. It is specified by the value of the Common Gateway Interface (CGI) variable REMOTE_ADDR.	No
  signerHashes	Base64	A SHA-256 hash of the public key, of the certificate, of the application signer. If there are more signers, each hash is comma separated. This can be used for detecting whether the application has been re-signed.	No
  userAgent	String	HTTP User agent from smart device application.	No
  deviceHash	Base64	SHA256 hash of the unique hardware device ID, of the client device.	Yes
  deviceManufacturer	String	The manufacturer of the device. Examples: "Apple", "Samsung"	Yes
  deviceModel	String	The device's model. Examples: "iPad2,2", "Nexus S"	Yes
  operatingSystemType	String	Indicates the operating system type of the device; either Android or iOS.	Yes
  applicationHash	Base64	SHA256 hash of the application name. The server can use this for detecting re-packaging.	No
  clientSideIp	JSON	An array containing the client network interfaces. This includes the type of the network and the IP address. The list can contain multiple interfaces if the user's device is connected to more than one at the time of the transaction. Examples: [{"Type":"Cellular","IPAddress":"123.123.123.123"}, {"Type":"Wifi","IPAddress":"124.124.124.124"}]	No
  hwKeyClientStatus	String	The status of the hardware protected key signature preformed by the Encap client SDK. See Hardware-protected key client statuses for possible values.	No
  hwKeyServerResult	String	The result of the hardware protected key signature verification on the Encap server. See Hardware-protected key server results for possible values.	No
  batteryLevel	Integer	Indicates the battery level of the device.	No
  isPowerConnected	Boolean	Indicates whether the device is being charged/connected to a charger.	No

The MobileID user API provides you with operations related to creating and managing users (sometimes referred to as identities) for MobileID.

Note: The request and response samples are for illustrative purposes only, and discrepancies can occur between the sample values in request and response objects.

Most operations in the MobileID service require a MobileID user, which is identified by a valid user ID (userId).

A user may optionally contain attributes such as an address or phone number, in the form of key-value pairs.

A MobileID user can have two different states:

The MobileID registration API provides you with operations related to registering devices for MobileID.

Note: The request and response samples are for illustrative purposes only, and discrepancies can occur between the sample values in request and response objects.

All registration operations return a registration response containing an operation state.

Registration modes

There are two registration modes (registrationMode) for creating and updating a registration:

Operation context

When you perform a registration, you can use our post-operation context (postOperationContext).

To learn more, see our operation context feature documentation.

The MobileID authentication API provides you with operations related to authentication and authorisation for MobileID.

Note: The request and response samples are for illustrative purposes only, and discrepancies can occur between the sample values in request and response objects.

All authentication operations return an authentication response containing an operation state.

Operation context

When you perform an authentication, you can use our pre-operation context (preOperationContext) and post-operation context (postOperationContext).

To learn more, see our operation context feature documentation.

The MobileID signature API provides you with operations related to signing for MobileID.

Note: The request and response samples are for illustrative purposes only, and discrepancies can occur between the sample values in request and response objects.

All signature operations return a signature response containing an operation state.

Operation context

When you perform a signing, you can use our pre-operation context (preOperationContext) and post-operation context (postOperationContext).

To learn more, see our operation context feature documentation.

About the signed JWT

The signing operation is similar to the authentication operation, however, we also return a signed JSON Web Token (JWT) of the transaction to you. This signed JWT can be stored; giving you a record of the user's transaction, which you can then validate using the Signicat signing certificate.

Note: The scope of this documentation is to describe the parameters and structure of a JWT in the context of MobileID.

The process for correctly validating a signed JWT is beyond the scope of this API reference documentation, but is well documented in external resources such as the respective RFC publications.

Signed JWT certificate options

You can determine how much of the signing certificate chain is embedded in the JWT by setting the required enumerated value from the table below. MobileID embeds the public key into the signature if you have specified the SINGLE or CHAIN signing certificate options.

JWT header

The MobileID JWT header is comprised of either 2 or 3 parts, depending on which signing certificate option is specified.

Example 1: JWT header

JWT header when the certificate option is NONE.

{
    "x5t#S256": "0456779b6966effdfc2d6d769edd3de25a7c295d27bdcc100efc8cf50f2a5372",
    "alg": "RS256",
}

Example 2: JWT header

JWT header when the certificate option is SINGLE.

{
    "x5t#S256": "0456779b6966effdfc2d6d769edd3de25a7c295d27bdcc100efc8cf50f2a5372",
    "x5c": [
        "MIIFwTCCA6mgAwIBAgIKcDEIzY8CWLQVtzANBgkqhkiG9w0BAQ0FADBqMQswCQYDVQQGEwJOTzEYMBYGA1UEYQwPTlRSTk8tOTgzMTYzMzI3MRMwEQYDVQQKDApCdXlwYXNzIEFTMSwwKgYDVQQDDCNCdXlwYXNzIENsYXNzIDMgVGVzdDQgUm9vdCBDQSBHMiBTVDAeFw0yMDExMDUxNzMwMThaFw00NTExMDUxNzMwMThaMGoxCzAJBgNVBAYTAk5PMRgwFgYDVQRhDA9OVFJOTy05ODMxNjMzMjcxEzARBgNVBAoMCkJ1eXBhc3MgQVMxLDAqBgNVBAMMI0J1eXBhc3MgQ2xhc3MgMyBUZXN0NCBSb290IENBIEcyIFNUMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAp5iPrsAqUNhggKgFKR9zummTTLthRtAwQ4FhqGJFavswFQJKHR27duFq3ctwdyr3JTUORpusJz8laX0PLH9m6yKpP4KUSEjPe9Ws2Qg/iEyt75TiaEu+xplZW3F7Fp09H9/WZOxhGm2z5gt/YDtot4mBbHbjh/MMj/z1mplRwyBIhOFgttwg9jUIlcmkJ0Udg+M+vaBfBY4xL7Q1m6VOZ5/BdUB6doeqWa3yBCEQekbWvaG6zeEXk2JQ/2OTQ7gKXNObgsuSO1jYphHG+i4+2H/RgNINTQMGf4RrvbO5A0VurWoibFL8H0IoC+DzRHgTddswz8iV3aO9BK57HjjHMgbzqR1m+Z1JhUn6gUo6uE4heHW00wlgnbVxGNl7VrNdPGFED/gxtzYDKHcyeJxc7EPpPasN+aWEGcooq6CE+GP/KGD3Wwrh316ydh6dfbtp50pZabZ+2EXc303MyVlyErrSUvHn5Hxv2Ekq1QRPY4aD/mZx3yl222oYXUCxHX5F1nQTdabDz70EtdQGUjRzv9aqZUZpKM0RU+kb2E2MTVb2Q7lBRbefDLl0pJA8R6IN2LOE/ICDZpD0tihB71rBTEABFoBPDokGioolqJ+F8l2w8B7HNg4sVxu872PDyGmwa2oR+1b9tIBCkjx681euWYdzxM3gZ2JCK5WovlEagm8CAwEAAaNpMGcwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUULP5PaDHJmWb2qiHb+kiPaJeaz8wDgYDVR0PAQH/BAQDAgEGMCUGCCsGAQUFBwEDBBkwFzAVBggrBgEFBQcLAjAJBgcEAIvsSQECMA0GCSqGSIb3DQEBDQUAA4ICAQAggOvmP9+CKPK1ghJfGShHXnx52vy9X8h81ODnvpvOJfbb7iB1+R//hUvtfcAB0DnRSSUEvXE0bkym2a85VsR2SizFrcHOSMBc5ZZHKB61V+s3F7cFLtk1qetcVsEY9jo7pa7elHB56jILHh4ivfVpXlrNifwtwVMGNH7fNkrVz1xLfeaYhgv63pdUL+XsZjbB4+EkYU5C3ZERsD5nnf0+g/14W17ktUMbuddwl4pMAcPuVd+aPD+LFfRC5mLB+/E/rZSutYPwGo31cDJAeLpm1D5t8WWZxMfGP77dHoGzEWDVB5od3e1S5cIhbLOUIZ2az00SzJ3i4HNj6GWDD4p8HzvBFZ3DA6oyC+ZyCpwMAQb+5JZbv5cOxlr4JqxtAPrs1oGO9H7qc0isvvWcTiP6F/WqvYoyQZWl28O7oqSv/GAmK2g/oXDQ+mjzQS6MIQGNdfb9ZN+i7E/XMCZ4N28Wk0V7jNpZz7R2O1FGJUfGn1z1ZByJQC+Og6dKQvwpj2E41qE1pYEYy4hpVxudLpuCUGSxkC0CcEV+7xL+BW04GpZn5TxAqN44/FpPCCW73Apk3cYd8LvfzKme5Z26jDNwp2ZDqru1zsQ5Mky/3F9ALB8CCu+5LZbmLHzsCDJoMnYDsfs0SweN2BqsZYi8eJcAErw76aunuR0F4g51KKlJtQ=="
    ],
    "alg": "RS256",
}

JWT payload

The JWT we produce contains the following claims:

Example: JWT payload

An example of a signed JWT, which is returned Base64-encoded in the operation response.

{
    "iss": "Signicat AS",
    "transactionData": "eyJ0cmFuc2FjdGlvbklkIjoiZWUxMmEyYTktYzIzYS00NjczLWEyZjgtNDU1MzI1OTczZGNiIiwiYWNjb3VudElkIjoiYS1zZGdlLU4yN0dqUFN6WE84SkxjZjhHMUFOIiwic3RhdGUiOiJDT01QTEVURUQiLCJvcGVyYXRpb25Qcm9wZXJ0aWVzIjp7ImF1dGhMZXZlbCI6IlRXT19GQUNUT1IiLCJjb3JyZWxhdGlvbklkIjoiM2VhZTU4MzAtM2VlMi00ZTJjLWEzNGYtMTczYmRhOTg1ZDU5IiwiYXV0aE1ldGhvZCI6IkRFVklDRV9BTkRST0lEX0JJT01FVFJJQ19QUk9NUFQiLCJzZW5kUHVzaCI6ZmFsc2UsInByZU9wZXJhdGlvbkNvbnRleHQiOnsidGl0bGUiOiJDb25zZW50IFNpZ24iLCJjb250ZW50IjoibG9rbyIsIm1pbWVUeXBlIjoidGV4dC9wbGFpbiJ9LCJwdXNoU2VudCI6ZmFsc2UsInNlc3Npb25FeHBpcnlUaW1lIjoiMjAyMi0xMS0xMFQxMzozNDo0MC4wNDBaIiwic2lnbmVkSnd0Q2VydGlmaWNhdGVPcHRpb24iOiJOT05FIn0sInJpc2tBdHRyaWJ1dGVzIjp7fSwiY3JlYXRlZCI6IjIwMjItMTEtMTBUMTM6MzM6MDkuOTExWiIsImNvbXBsZXRlZCI6IjIwMjItMTEtMTBUMTM6MzM6MTYuMDM1WiIsImRldmljZSI6eyJpZCI6ImM3NDNiNTg4LWY1N2UtNGZhYy04OWMyLTZmYWMyMDU4OTc2OCIsIm5hbWUiOiJzYW1wbGVEZXZpY2UiLCJzdGF0ZSI6IkFDVElWRSIsImxhc3RPcGVyYXRpb25UeXBlIjoiU0lHTklORyIsImxhc3RVc2VkIjoiMjAyMi0xMS0xMFQxMzozMzoxNi4wMDhaIiwiY3JlYXRlZCI6IjIwMjItMTEtMTBUMTI6MDk6MDQuMDkyWiJ9LCJ1c2VyIjp7ImV4dGVybmFsUmVmIjoiZGV2NSIsImlkIjoiZTY5N2ExMzEtMGZlMy00MDgyLTljNWItOTk0MTE3MDMyOWQyIiwiY3JlYXRlZCI6IjIwMjItMTEtMTBUMTI6MDg6NTQuMjQ4WiIsImxhc3RVc2VkIjoiMjAyMi0xMS0xMFQxMzozMzoxNS45ODZaIiwic3RhdGUiOiJBQ1RJVkUifX0=",
    "sub": "e697a131-0fe3-4082-9c5b-9941170329d2",
    "iat": "1668087196",
    "jti": "ab993e6b-6788-47cb-803e-38fc5413b8ae",
}

The MobileID device management API provides you with operations related to device management for MobileID.

Note: The request and response samples are for illustrative purposes only, and discrepancies can occur between the sample values in request and response objects.

All device management operations require:

• A MobileID user, identified by a user ID (userID).
• A registered device, identified by a device ID (deviceID).

The MobileID passport scan API provides you with operations for our MobileID passport scan feature.

Note: The request and response samples are for illustrative purposes only, and discrepancies can occur between the sample values in request and response objects.

All passport scan operations return a passport scan response containing an operation state.

To use our passport scan feature, we need to set up and configure all necessary properties for you. You can request this by contacting us at support@signicat.com.

You can find more information about passport scan in our feature documentation.