Signicat MobileID API reference (1.0)

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 Products, then select MobileID..

4. Click the Add MobileID 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.

When an asynchronous operation completes, or when MobileID gets a notification that a device has changed state, MobileID publishes an event with the operation result.

You can use the Signicat Events service to subscribe to these events, so that you automatically receive the result at your specified notification URI. This is often referred to as callback.

To learn more about MobileID events and how to set up callback, see our Events (MobileID) feature documentation.

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.

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.
• The Platform column indicates whether the risk attribute is available for Android, iOS, or both.

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.

You can read more about the signature operation in our Signature feature documentation.

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.

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

THIS FEATURE IS DEPRECATED

The MobileID Passport scan feature is now deprecated, and is replaced by our ReuseID solution.

ReuseID allows you to perform ID document and biometric verification for either onboarding end-users to MobileID or existing MobileID users.

You can read more about this update in our release notes.

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.