Skip to main content

Quick start guide

Learn how to test out a MobileID authentication using the Authenticator App and the MobileID API.

This quick start guide shows you how to:

  1. Get set up for testing MobileID with the Authenticator App.
  2. Create a MobileID user.
  3. Register a MobileID device
  4. Perform an authentication.
Want to try MobileID without making API requests?

This guide requires that you make API requests using a tool of your choice.

If you want to try out MobileID without making API requests, then you can use the Try it out page in the Signicat Dashboard. Here, you can use a button to trigger MobileID operations instead.

Prerequisites​

1. Initial preparations​

Before you start, you need to have:

Add a domain

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

Our recommendation

We recommend that you create a sandbox account to test our services before going live. Sandbox and production accounts must be set up separately.

How do I complete the initial preparations?

To sign up to Signicat for free and complete the initial preparations:

  1. Sign up to the Signicat Dashboard and register your profile.
  2. Ensure that you have created an organisation.
  3. Create an account. To do this:
    1. Go to Signicat Dashboard > Organisation, then click the + Add account button.
    2. Enter an account name, choose the type of account that you want to create, then click the Create button.

2. Get client credentials​

To authenticate against our APIs, you need to set up an API client. To do this:

  1. Go to Signicat Dashboard > Settings > API clients.
  2. Click the + Add client button.
  3. Enter a name for the client, then click the Create button.
  4. You must have at least once client secret, so click Add secret button. This take you to the Secrets tab on the client details page.
  5. Click the + Add secret.
  6. Enter a name for the client secret, then click Generate secret.
Store the client secret

Make sure that you store the client secret in a secure place. This is the only time that you can view the client secret in clear text.

If you do lose your client secret, then you can always generate another one.

Want to learn more?

For more information about creating an API client, see the Accessing Signicat API products page.

3. Set permissions​

To connect to this API, you need to configure the correct permissions for you API client. To do this:

  1. Go to Signicat Dashboard > Settings > API clients.
  2. Click the Edit button beside the client that you created.
  3. Click the Permissions tab, then click the + Select product button.
  4. Tick the boxes for MobileID API and MobileID Admin API, then click the Update button.
Note

If you cannot access the Permissions tab, then you do not have the correct role to manage permissions for your organisation. To receive access, contact your organisation administrator.

For more information, see the Managing roles and permissions page

Want to learn more?

For more information about setting permissions, see the Permissions section on the Accessing Signicat API products page.

4. Onboard to MobileID​

You need to onboard your account to MobileID. To do this:

  1. Go to Signicat Dashboard > Products > MobileID.
  2. Click the + Add MobileID button.

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​

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.

To set up MobileID in Postman and obtain an access token:

  1. Open Postman.
  2. 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

    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.
  3. Create variables. To do this, click the Variables tab, and add the following:
    Screenshot showing creation of variables in Postman

    Screenshot showing creation of variables in Postman

  4. Set up authorisation. To do this, go to the Authorization tab and and update the following:
    Screenshot showing set up of authorisation in Postman

    Screenshot showing set up of authorisation in Postman

  5. Click on the Get new access token button to get an access token.
  6. To add the token to the requests, click Proceed, then Use Token.
  7. Save your changes.
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.

The Authenticator App is our white-label mobile application which enables you to perform operations on a mobile device, so that you can start testing out MobileID as quickly as possible.

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:

iOS​

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

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

    QR code to install the iOS Authenticator App

  3. Install the latest version.

Android​

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

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

    QR code to install the Android Authenticator App

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

How to obtain these values​

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

  1. Go to Signicat Dashboard > Products > MobileID > Details.
  2. Click on Quick configuration in the top-right corner.
Manually add values

If you do not wish to use the QR code scanner, then you can also find the Application ID value under the Account tab, and the Public key value under the E2E keys tab.

How to set these values​

Other options

It is also possible to select a configuration from the dropdown list, or manually add your own configuration by clicking +.

Try MobileID​

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

1. Create a MobileID user​

To create a MobileID user:

  1. In Postman, navigate to Signicat MobileID API reference > User > Create user.
  2. 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"
       }
    }
  3. 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:

  1. In Postman, navigate to Signicat MobileID API reference > Registration > Start registration.
  2. 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"
    }
  3. Click the Send button.
  4. You have now started a registration operation. The response contains an activationCode, which you need in the next step.

    Show activation code as QR code in Postman

    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 in the Authenticator App.

    To do this, add the following snippet to 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"
      }
    }
  5. Open the Authenticator App.
  6. Click on the button to start the registration operation on the device.
  7. Scan or enter the activationCode that was obtained in Step 4.
    Note

    The activation code is only valid until the session expiry time (sessionExpiryTime).

  8. Select a PIN code.
  9. Select if you want to activate biometrics.
  10. In Postman, navigate to Registration > Get state of ongoing registration.
  11. Under the Params tab, update the value of transactionId to the value you obtained in the Start registration response.
  12. 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:

  1. In Postman, navigate to Signicat MobileID API reference > authentications > Start authentication.
  2. 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"
          }
       }
    }
  3. 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"
       }
    }
  4. Open the Authenticator App.
  5. 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.
  6. Click the Approve button.
  7. In Postman, navigate to authentications > Get state of ongoing authentication.
  8. Under the Params tab, update the value of transactionId to the value you obtained in the Start authentication response.
  9. 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 features in our feature guides
API reference
Look up all API endpoints and properties. View sample requests and responses
Last updated:
On this page