Quick start guide

This quick start guide shows you how to:

Get set up so that you can test MobileID with our Authenticator App.
Create a MobileID user, register a MobileID device, and perform an authentication.

Prerequisites

1. Before you start

If you do not have an account already, then you need to sign up to Signicat.
In the Signicat Dashboard, you must create an organisation and create an account.
Add a domain
It is also possible to add a domain, but this is not required for MobileID.
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.
To use MobileID, you need to set the required permissions. Ensure that you select both MobileID API and MobileID Admin API as permissions.

2. Add MobileID to your account

Next, you need to add MobileID to your account. To do this:

Log in to the Signicat Dashboard.
Go to Products > MobileID
Click the Add MobileID button.

Success!

You have now added MobileID to your account.

Set it up

Next, you have to set up a tool for triggering operations, and access our Authenticator App to perform them.

1. Set up MobileID in Postman

You need to set up MobileID in Postman.

Using other tools

This guide provides steps for using Postman as a tool for initiating the APIs, however, you can use the preferred tool of your choice.

Open Postman.
Import the collection. To do this:
1. Navigate to the Collections tab on the left-hand side of the screen, then click the Import button.
Screenshot showing import of MobileID collection into Postman
1. In the blank field in the dialogue box, paste the URL to our MobileID API specification https://api.signicat.com/mobileid/core/openapi.json.
  Our recommendation
  We recommend that you generate the request and response parameters from the examples in the schema, and that you create folders according to the tags. To do this:
  1. Click the View import settings button.
  2. In the Parameter generation section, select Example from the dropdown menu.
  3. In the Folder organization section, select Tags from the dropdown menu.
2. Click the Import button in the dialogue box to finalise the import.

Create variables. To do this, click the Variables tab, and add the following:

Variable	Value
`baseUrl`	This variable becomes present after import. Make sure that the value is `https://api.signicat.com/mobileid/core`.
`authClientID`	Enter the Client ID obtained when you created an API client.
`authClientSecret`	Enter the Client Secret obtained when you created an API client.

Screenshot showing creation of variables in Postman

Set up authorisation. To do this, go to the Authorization tab and and update the following:
Name Value
Type OAuth 2.0
Grant type Client Credentials
Access Token URL https://api.signicat.com/auth/open/connect/token
Client ID {{authClientID}}
Client Secret {{authClientSecret}}
Scope signicat-api

Screenshot showing set up of authorisation in Postman
Click on the Get new access token button to get an access token.
To add the token to the requests, click Proceed, then Use Token.
Save your changes.

Name	Value
Type	`OAuth 2.0`
Grant type	`Client Credentials`
Access Token URL	`https://api.signicat.com/auth/open/connect/token`
Client ID	`{{authClientID}}`
Client Secret	`{{authClientSecret}}`
Scope	`signicat-api`

Auto-refresh your access token

To automatically refresh your access token after it has expired, enable the Auto-refresh token toggle button under the Authorization tab.

You can only enable auto-refresh tokens after you have received your first valid token.

Success!

You have now set up Postman for the MobileID APIs.

2. Install our Authenticator App

To perform the operations on a mobile device you can use our Authenticator App.

This is our white-label mobile application, and will enable you to get hands-on with testing out our product the fastest.

Want to use our SDK instead?

It is also possible to use our SDK and integrate it into your own app instead. To get access to the SDK, you can contact us by creating a support ticket in the Signicat Dashboard.

When using the SDK, you need to configure the controller to use your MobileID account. To do this, you use the same values as those required to configure the Authenticator App:

See the configure our Authenticator app section for the values to configure.
See our Android and iOS SDK documentation for details on how to configure the controller.

iOS

To install our Authenticator App on your iPhone, you have to:

Install Apple's TestFlight app.
Scan the QR code below on your mobile device:
QR code to install the iOS Authenticator App
Install the latest version.

Android

To install our Authenticator App on your Android, you have to:

Scan the QR code below on your mobile device:
QR code to install the Android Authenticator App
Install the latest version.

3. Configure our Authenticator App

Once you have installed the Authenticator App, you need to configure it to use your MobileID account.

To do this, you need to update the following values:

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.

Obtaining the values

To get your application ID (applicationId) and public E2E key (publicKey), you need to:

Log in to the Signicat Dashboard.
Go to Products > MobileID > Details
Use the tabs for Account and E2E keys to see your Application ID and Public key.

Set your values

Either select a configuration from the dropdown list, or manually add your own configuration by clicking `+`.

1/2 - Open the Authenticator app, then click on the cog-wheel in the top-right corner.

Test it out

You have now completed all required preparations, and are now ready to perform MobileID operations.

1. Create a MobileID user

You can now create a MobileID user. To do this:

In Postman, navigate to Signicat MobileID API reference > User > Create user.

Under the Body tab, you can input your own request body.

Example: Request to create a MobileID user
{
   "attributes": {
      "first_name": "Jane",
      "last_name": "Smith"
   }
}

Click the Send button.

Example: Response from creating a MobileID user
{
    "id": "76bfe9e6-1fe2-4b92-b742-a66015a98981",
    "created": "2023-08-16T11:25:50.923Z",
    "state": "ACTIVE",
    "attributes": {
        "last_name": "Smith",
        "first_name": "Jane"
    }
}

Success!

You have now created a MobileID user.

Our recommendation

We recommend that you save the id of your MobileID user (user ID), as it is needed in future operations.

2. Register a MobileID device

Now that you have created a MobileID user, you can register a MobileID device. To do this:

In Postman, navigate to Signicat MobileID API reference > Registration > Start registration.
Under the Body tab, you can input your own request body. For this API, it is required to set the user ID (userId). This is the ID of the MobileID user that you created in the previous section.
Example: Request to register a MobileID device
```
{
  "userId": "76bfe9e6-1fe2-4b92-b742-a66015a98981"
}
```
Click the Send button.

You have now started a registration operation. The response contains an activationCode, which you need in the next step.

Our recommendation

To get the best the user experience, Postman can show the activation code as a QR code. This means that you do not have to manually type the code into the app.

Add the following snippet to the Script > Post-response in the POST request:

let response = pm.response.json();

let qrcTemplate = '<img width="250" height="250" src="https://qrcode.tec-it.com/API/QRCode?data=' + encodeURIComponent(response.data.activationCode) + '">';
pm.visualizer.set(qrcTemplate, {});

Example: Response from registering a MobileID device
{
  "accountId": "a-spge-7NS53Bt6di0YlzA9SYQO",
  "transactionId": "c9a0d33d-3366-4561-b47f-ec48428e2962",
  "state": "PENDING",
  "created": "2023-08-16T11:33:08.537Z",
  "device": {},
  "user": {
    "id": "76bfe9e6-1fe2-4b92-b742-a66015a98981",
    "created": "2023-08-16T11:25:50.923Z",
    "state": "ACTIVE"
  },
  "operationProperties": {
    "activationCode": "057771",
    "registrationMode": "REGISTRATION",
    "sessionExpiryTime": "2023-08-16T11:34:38.441Z"
  }
}

Open the Authenticator App.
Click on the button to start the registration operation on the device.
Scan or enter the activationCode that was obtained in Step 4.
Note
The activation code is only valid until the session expiry time (sessionExpiryTime).
Select a PIN code.
Select if you want to activate biometrics.
In Postman, navigate to Registration > Get state of ongoing registration.
Under the Params tab, update the value of transactionId to the value you obtained in the Start registration response.

Click the Send button.

Example: Response from fetching the state of a MobileID registration
    {
        "accountId": "a-spge-7NS53Bt6di0YlzA9SYQO",
        "transactionId": "c9a0d33d-3366-4561-b47f-ec48428e2962",
        "state": "COMPLETED",
        "created": "2023-08-16T11:36:57.759Z",
        "completed": "2023-08-16T11:37:19.110Z",
        "device": {
            "id": "dc55de99-b11f-40ad-8c12-adb98be9ec61",
            "state": "ACTIVE",
            "lastOperationType": "REGISTRATION",
            "lastUsed": "2023-08-16T11:37:19.122Z",
            "created": "2023-08-16T11:37:19.111Z"
        },
        "user": {
            "id": "76bfe9e6-1fe2-4b92-b742-a66015a98981",
            "created": "2023-08-16T11:25:50.923Z",
            "lastUsed": "2023-08-16T11:37:19.100Z",
            "state": "ACTIVE"
        },
        "operationProperties": {
            "activationCode": "662815",
            "authLevel": "TWO_FACTOR",
            "registrationMode": "REGISTRATION",
            "sessionExpiryTime": "2023-08-16T11:38:27.660Z"
        }
    }

Success!

You have now registered and activated a MobileID device.

Our recommendation

We recommend that you save the id of your MobileID device (device ID), as it is needed in future operations.

3. Authenticate your MobileID user

Now that you have registered a MobileID device, you can authenticate with that device. To do this:

In Postman, navigate to Signicat MobileID API reference > authentications > Start authentication.

Under the Body tab, you can input your own request body. For this API, it is required to set both the user ID (userId) and the device ID (deviceId). These are the IDs of the MobileID user and MobileID device that you obtained in the previous sections.

Example: Request to authenticate
{
   "userId": "76bfe9e6-1fe2-4b92-b742-a66015a98981",
   "device": {
      "id": "dc55de99-b11f-40ad-8c12-adb98be9ec61"
   },
   "operationProperties": {
      "preOperationContext": {
         "content": "Approve your first MobileID authentication",
         "mimeType": "text/plain"
      },
      "postOperationContext": {
         "content": "Cool! You have successfully completed a MobileID authentication",
         "mimeType": "text/plain"
      }
   }
}

Click the Send button.

Example: Response from the authentication
{
   "accountId": "a-spge-7NS53Bt6di0YlzA9SYQO",
   "transactionId": "e33c5cd4-03d2-42ca-acc1-407a72c234ce",
   "state": "PENDING",
   "created": "2023-08-16T11:53:24.863Z",
   "device": {
      "id": "dc55de99-b11f-40ad-8c12-adb98be9ec61",
      "state": "ACTIVE",
      "lastOperationType": "AUTHENTICATION",
      "lastUsed": "2023-08-16T11:51:14.703Z",
      "created": "2023-08-16T11:37:19.111Z"
   },
   "user": {
      "id": "76bfe9e6-1fe2-4b92-b742-a66015a98981",
      "created": "2023-08-16T11:25:50.923Z",
      "lastUsed": "2023-08-16T11:51:14.693Z",
      "state": "ACTIVE"
   },
   "operationProperties": {
      "postOperationContext": {
         "content": "Cool! You have successfully completed a MobileID authentication",
         "mimeType": "text/plain"
      },
      "preOperationContext": {
         "content": "Approve your first MobileID authentication",
         "mimeType": "text/plain"
      },
      "pushSent": true,
      "sessionExpiryTime": "2023-08-16T11:54:54.955Z"
   }
}

Open the Authenticator App.
The app shows a dialogue box with the pre-operation context (preOperationContext). If you do not see the pre-operation context, then you can use the reload button.
Click the Approve button.
In Postman, navigate to authentications > Get state of ongoing authentication.
Under the Params tab, update the value of transactionId to the value you obtained in the Start authentication response.

Click the Send button.

Example: Response from fetching the state of an authentication
{
    "accountId": "a-spge-7NS53Bt6di0YlzA9SYQO",
    "transactionId": "e33c5cd4-03d2-42ca-acc1-407a72c234ce",
    "state": "COMPLETED",
    "created": "2023-08-16T11:53:24.863Z",
    "completed": "2023-08-16T11:53:37.407Z",
    "device": {
        "id": "dc55de99-b11f-40ad-8c12-adb98be9ec61",
        "state": "ACTIVE",
        "lastOperationType": "AUTHENTICATION",
        "lastUsed": "2023-08-16T11:53:37.392Z",
        "created": "2023-08-16T11:37:19.111Z"
    },
    "user": {
        "id": "76bfe9e6-1fe2-4b92-b742-a66015a98981",
        "created": "2023-08-16T11:25:50.923Z",
        "lastUsed": "2023-08-16T11:53:37.382Z",
        "state": "ACTIVE"
    },
    "operationProperties": {
        "postOperationContext": {
            "content": "Cool! You have successfully completed a MobileID authentication",
            "mimeType": "text/plain"
        },
        "authLevel": "TWO_FACTOR",
        "authMethod": "DEVICE_IOS_FACE_ID",
        "preOperationContext": {
            "content": "Approve your first MobileID authentication",
            "mimeType": "text/plain"
        },
        "pushSent": true,
        "sessionExpiryTime": "2023-08-16T11:54:54.955Z"
    }
}

Success!

You have now completed a MobileID authentication.

Want to learn more?

You can find information about all of the different authentication endpoints in our MobileID API reference documentation.

Learn more

You can explore our developer documentation to learn more about what you can do with MobileID and further test out the product.

Use cases

Get inspired by how you can use MobileID in different use cases

How it works

Learn about the operations that make up the integration process

Features

Learn about MobileID's features in our feature guides

API reference

Look up all API endpoints and properties. View sample requests and responses

Prerequisites​

1. Before you start​

2. Add MobileID to your account​

Set it up​

1. Set up MobileID in Postman​

2. Install our Authenticator App​

iOS​

Android​

3. Configure our Authenticator App​

Obtaining the values​

Set your values​

Test it out​

1. Create a MobileID user​

2. Register a MobileID device​

3. Authenticate your MobileID user​

Learn more​

Prerequisites

1. Before you start

2. Add MobileID to your account

Set it up

1. Set up MobileID in Postman

2. Install our Authenticator App

iOS

Android

3. Configure our Authenticator App

Obtaining the values

Set your values

Test it out

1. Create a MobileID user

2. Register a MobileID device

3. Authenticate your MobileID user

Learn more