# Migration guide

The following guide will help you migrate from Signicat Authentication API v1 to v2.

# Endpoints: v1 -> v2 mapping

v1 v2
Base URL: https://api.idfy.io/identification Base URL: https://api.signicat.io/identification/v2
GET /session?requestId={id} GET /sessions/{id}
POST /session POST /sessions
PUT /sessions/invalidate?requetsId={id} POST /sessions/{id}/invalidate
GET /log/filter/{year} GET /sessions
Note: Active sessions are not included in this list. The session data returned from this endpoint does not contain any personal information or other sensitive data about the user.
GET /log/requestId/{id} Not available
Note: Use the GET /sessions endpoint to list previously created sessions.
POST /no/bankid/mobile POST /sessions
Note: Headless BankID on mobile sessions are now created with the POST /sessions endpoint using the headless flow.

# New features

  • A simpler, cleaner REST API
  • Specify any combination of ID providers to allow for a given session
  • A modern, customizable UI with theming support
  • Support for headless Norwegian BankID and Swedish BankID
  • New IDPs:
    • SMS OTP
    • Freja
    • Microsoft (Azure AD)
    • GitHub
    • LinkedIn
    • itsme
    • iDIN
    • DigiD
    • eHerkenning

More features will be added as the API evolves.

# Differences and migration considerations

The new API endpoints behave somewhat differently from the previous version. Simply updating the endpoint URLs will in some cases result in errors in your application.

# New statuses

v1 v2
SUCCESS success
ERROR failed
USERABORTED user_aborted
INVALIDATED invalidated
TIMEOUT timed_out
CREATED created
USERINITIATED user_initiated

# Session lifetime

A session is active for 10 minutes after its creation, after which the session URL can no longer be used. The expiry is returned as the expires property in the response when you create and retrieve a session.

We will store personal information and other sensitive data about the user for 1 hour after session creation, which means that you will have to retrieve and store the information you need on your end within this timeframe. After 1 hour, all sensitive data is deleted from our system and only a subset of the session data will be returned from the API:

  • id
  • created
  • expires
  • status
  • language
  • flow
  • provider
  • environment.userAgent
  • externalReference
  • error

# Session invalidation

In the v1 API it was recommended to invalidate completed sessions in order to prevent session re-use.

This is not necessary in the v2 API as it is not possible to re-use completed sessions. Only sessions that have yet to be completed can be invalidated.

# The include property

By default, when a user has authenticated themselves, only the providerId - the user’s unique ID for a given IDP - is collected and returned as part of the session’s identity object.

To request additional information about the user, this must be specified with the include property when creating the session.

# Example

{
  "include": [
    "name",
    "date_of_birth",
    "nin"
  ]
}

The following table displays the valid values for include and the session properties that will be returned:

Value Returned properties
name identity.firstName
identity.middleName
identity.lastName
identity.fullName
date_of_birth identity.dateOfBirth
phone_number identity.phoneNumber
nin identity.nin
email identity.email
organization identity.organization

# New concept: flows

In the v2 API a new concept, flows, has been introduced. When creating a session you must select between one of three flows:

# Redirect

Use this flow if you intend to redirect the user to the identification URL. The user is redirected back to you when authentication is completed.

# Iframe

Use this flow if you intend to embed the identification URL in an iframe. A message will be dispatched to the parent window using postMessage when the authentication is completed.

# Headless

Use this flow if you want to start a session directly on the user’s device with no UI involved (typically from a backend or app to backend system). Currently only supported by Norwegian BankID on mobile and Swedish BankID.

# Iframe flow messages

When using the iframe flow, messages are sent to your page with postMessage (opens new window) when a session is either successful, aborted or failed due to an error. The URI of the parent window must match the URI that is specified in iframeSettings.postMessageTargetOrigin when the session is created.

You must listen to the dispatched messages by registering an event listener:

window.addEventListener('message', function(event) {
  if (event.origin !== 'https://id.idfy.io')
    return;
  
  const data = JSON.parse(event.data);
  console.log(data.status); // => 'success/aborted/error'
});

It is important to validate the origin before processing the message because the message handler accepts messages from any URI.

The origin is https://id2-test.idfy.io for our test environment, and https://id.idfy.io for production.

TIP

We are in the process of moving all of our services to *.signicat.io domains. To make sure that your application is ready for this change, please include https://id-test.signicat.io (test environment) and https://id.signicat.io (production environment) as valid origins.

The message object has the following structure:

{
  "sessionId": "<sessionId>",
  "status": "<success/aborted/error>"
}

# Examples

Below are some examples on how you would use v1 and v2 to create a new session.

# Redirect flow

# v1 approach

POST /session

{
  "IdentityProvider": "NO_BANKID_MOBILE",
  "ReturnUrls": {
    "Error": "https://secure.wayneenterprises.com/error",
    "Abort": "https://secure.wayneenterprises.com/abort",
    "Success": "https://secure.wayneenterprises.com/success"
  },
  "Language": "NO",
  "GetSocialSecurityNumber": true,
  "ExternalReference": "123456789"
}

# v2 approach

POST /sessions

{
  "allowedProviders": [
    "no_bankid_mobile"
  ],
  "language": "no",
  "flow": "redirect",
  "include": [
    "name",
    "nin"
  ],
  "redirectSettings": {
    "successUrl": "https://secure.wayneenterprises.com/success",
    "abortUrl": " https://secure.wayneenterprises.com/abort",
    "errorUrl": " https://secure.wayneenterprises.com/error"
  },
  "externalReference": "123456789"
}

# Iframe flow

# v1 approach

POST /session

{
  "IdentityProvider": "NO_BANKID_MOBILE",
  "iFrame": {
    "Domain": "https://example.com",
    "WebMessaging": true
  },
  "Language": "NO",
  "GetSocialSecurityNumber": true,
  "ExternalReference": "123456789"
}

# v2 approach

POST /sessions

{
  "allowedProviders": [
    "no_bankid_mobile"
  ],
  "language": "no",
  "flow": "iframe",
  "include": [
    "name",
    "nin"
  ],
  "iframeSettings": {
    "parentDomains": ["https://secure.wayneenterprises.com"],
    "postMessageTargetOrigin": "https://secure.wayneenterprises.com"
  },
  "externalReference": "123456789"
}

# Headless flow

# v1 approach

POST /no/bankid/mobile

{
  "MobileNumber": "99887766",
  "DateOfBirth": "071283",
  "GetSocialSecurityNumber": true,
  "ExternalReference": "123456789"
}

# v2 approach

POST /sessions

{
  "allowedProviders": [
    "no_bankid_mobile"
  ],
  "flow": "headless",
  "include": [
    "name",
    "nin"
  ],
  "externalReference": "123456789",
  "prefilledInput": {
    "phoneNumber": "+4799887766",
    "dateOfBirth": "1983-12-07" // For Norwegian BankID on Mobile the DDMMYY format is also supported.
  }
}

Reference code

The reference code that is displayed on the end-user's mobile device has been renamed from MerchantRef to securityReference in the v2 API. See our API reference for detailed information about all the available endpoints and properties.

Help us improve

Did you find the information you were looking for? If not, have a look in our community pages or create a new post.

Are there any features you think are missing? Anything you'd like to see on our site? You can share your thoughts in this dedicated section.

Last updated: 4/23/2021, 2:09:01 PM