Config Reference

Identification Config Reference

Creating the client for identification

const eidEasyClient = window.eidEasyBrowserClient.createClient({
    clientId: '2IaeiZXbcKzlP1KvjZH9ghty2IJKM8Lg', // required
    redirectUri: 'http://localhost/', // required
    apiEndpoints: { // required
      identityStart: () => 'https://eid-sample-app.test/api/identity/start',
      identityFinish: () => 'https://eid-sample-app.test/api/identity/finish',
    },
    countryCode: 'EE', // required
    language: 'et',
    sandbox: true,
    oauthParamState: 'custom-state-value', // this gets used only in case of identification methods
});

Client Settings

OptionTypeDefaultDescription
clientIdstringundefinedRequired. Get from id.eideasy.com after signing up.
redirectUristringundefinedRequired. This gets used for redirects back to your application e.g. when using eParaksts mobile. The value of redirectUri has to match with the "Oauth redirect_uri(s)" setting you provided in your eID Easy admin page.
apiEndpoints.identityStartfunctionundefinedRequired. This should return your server endpoint for the identity start request. See the "Implementing the identityStart and identityFinish endpoints" section for more information.
apiEndpoints.identityFinishfunctionundefinedRequired. This should return your server endpoint for the identity finish request. See the "Implementing the identityStart and identityFinish endpoints" section for more information.
countryCodestringundefinedRequired. ISO 3166-1 alpha-2open in new window country code
sandboxbooleanfalseWhether to use the sandboxopen in new window mode.
languagestring'en'Two letter ISO 639-1open in new window language code.
oauthParamStatestringundefinedValue of the OAuth state param.

Implementing the identityStart and identityFinish endpoints

You should implement and expose two endpoints on your server to handle the identity start and identity finish requests.

identityStart endpoint should take the request body sent by the browser-client, add your client_id and secret to it and send it to https://id.eideasy.com/api/identity/{client_id}/{method}/start.

It should then return the response from https://id.eideasy.com/api/identity/{client_id}/{method}/start back to the browser-client.

identityFinish endpoint should take the request body sent by the browser-client, add your client_id and secret to it and send it to https://id.eideasy.com/api/identity/{client_id}/{method}/complete.

If the response from https://id.eideasy.com/api/identity/{client_id}/{method}/complete contains {"status": "OK" }, then the user has successfully authenticated and you can proceed with logging in the user.

In all other cases, you can return the response from https://id.eideasy.com/api/identity/{client_id}/{method}/complete back to the browser-client and the browser-client will handle the error.

See the diagram below for request examples and a visual representation of the flow.

eideasy-embedded-auth-flow

Identification with an ID Card

eidEasyClient.identification.idCard.start({
   fail: (error) => {
      // do something with the error
   },
   success: (result) => {
      // do something with the result
   },
   finished: () => {
      // the process has finished, you can do some clean up like hiding a loader here
   },
});

idCard identification settings

OptionTypeDefaultDescription
failfunctionundefinedThis function gets called when the authentication process failed.
successfunctionundefinedThis function gets called when the authentication process succeeds.
finishedfunctionundefinedThis function gets called when the authentication process has either failed or succeeded. This means that this function gets called always, no matter the authentication result. For example, it can be useful to hide a loading spinner at the end of the authentication process or to do some other clean up work.

Identification with Smart-ID

eidEasyClient.identification.smartId.start({
   idcode: '10101010005', // required
   started: (result) => {
      // do something with the result
      // e.g. display the result.data.challenge code
   },
   fail: (error) => {
      // do something with the error
   },
   success: (result) => {
      // do something with the result
   },
   finished: () => {
      // the process has finished, you can do some clean up like hiding a loader here
   },
});

smartId identification settings

OptionTypeDefaultDescription
idcodestringundefinedRequired. End user's personal identification code
startedfunctionundefinedThis function gets called when the authentication process has started. The argument object of this function contains the challenge (response.data.challenge) you can display to the end-user.
failfunctionundefinedThis function gets called when the authentication process failed.
successfunctionundefinedThis function gets called when the authentication process succeeds.
finishedfunctionundefinedThis function gets called when the authentication process has either failed or succeeded. This means that this function gets called always, no matter the authentication result. For example, it can be useful to hide a loading spinner at the end of the authentication process or to do some other clean up work.

Identification with Mobile ID

eidEasyClient.identification.mobileId.start({
   idcode: '60001019906', // required
   phone: '+37200000766', // required
   started: (result) => {
      // do something with the result
      // e.g. display the result.data.challenge code
   },
   fail: (error) => {
      // do something with the error
   },
   success: (result) => {
      // do something with the result
   },
   finished: () => {
      // the process has finished, you can do some clean up like hiding a loader here
   },
});

mobileId identification settings

OptionTypeDefaultDescription
idcodestringundefinedRequired. End user's personal identification code
phonestringundefinedRequired. End user's phone number, must have the country codeopen in new window prefixed with a '+' sign, e.g. +37200000766
startedfunctionundefinedThis function gets called when the authentication process has started. The argument object of this function contains the challenge (response.data.challenge) you can display to the end-user.
failfunctionundefinedThis function gets called when the authentication process failed.
successfunctionundefinedThis function gets called when the authentication process succeeds.
finishedfunctionundefinedThis function gets called when the authentication process has either failed or succeeded. This means that this function gets called always, no matter the authentication result. For example, it can be useful to hide a loading spinner at the end of the authentication process or to do some other clean up work.

Identification with eParaksts mobile

eParaksts Mobile is an OAuth2 based method, so:

  1. user gets redirected to the eParaksts page where they have to enter their user number
  2. eParaksts then asks the user for confirmation on their cellphone
  3. user gets redirected back to the redirectUri specified in the eidEasyClient settings with a token you can use to fetch data
eidEasyClient.identification.eParakstsMobile.start({
   redirect: (context) => {
      console.log(context);
      // you can do the redirect here yourself should you wish so
      // window.location.href = context.redirectUrl;
      return {
         data: null,
      };
   },
});

eParakstsMobile identification settings

OptionTypeDefaultDescription
redirectfunctionundefinedYou can use this setting to override the default redirection functionality

Identification with Freja eID

eidEasyClient.identification.frejaEid.start({
   idcode: 'xxxxxxxxxxxxx', // required
   started: () => {
      // identification process has started,
      // Freja eID app will prompt the user to approve the identification request
   },
   fail: (error) => {
      // do something with the error
   },
   success: (result) => {
      // do something with the result
   },
   finished: () => {
     // the process has finished, you can do some clean up like hiding a loader here
   },
});

Freja eID identification settings

OptionTypeDefaultDescription
idcodestringundefinedRequired. End user's personal identification code
startedfunctionundefinedThis function gets called when the authentication process has started, Freja eID app will prompt the user to approve the identification request.
failfunctionundefinedThis function gets called when the authentication process failed.
successfunctionundefinedThis function gets called when the authentication process succeeds.
finishedfunctionundefinedThis function gets called when the authentication process has either failed or succeeded. This means that this function gets called always, no matter the authentication result. For example, it can be useful to hide a loading spinner at the end of the authentication process or to do some other clean up work.

Identification with ZealiD

When the ZealiD identification process starts, eidEasyClient will automatically create a ZealId iframe and start listening for messages originating from that iframe. You just have to provide a DOM element (the "iframeHolder" setting in the example below) to which eidEasyClient can append the iframe.

eidEasyClient.identification.zealId.start({
   iframeHolder: document.getElementById('zealIdIframeHolder'), // Required. DOM element whose content gets replaced with the ZealiD's iframe
   fail: (error) => {
      // do something with the error
   },
   success: (result) => {
      // do something with the result
   },
   finished: () => {
     // the process has finished, you can do some clean up like hiding a loader here
   },
});

ZealiD identification settings

OptionTypeDefaultDescription
iframeHolderDOM elementundefinedRequired. DOM element whose content gets replaced with the ZealiD's iframe
failfunctionundefinedThis function gets called when the authentication process failed.
successfunctionundefinedThis function gets called when the authentication process succeeds.
finishedfunctionundefinedThis function gets called when the authentication process has either failed or succeeded. This means that this function gets called always, no matter the authentication result. For example, it can be useful to hide a loading spinner at the end of the authentication process or to do some other clean up work.

Identification with Austrian Handy Signatur

Austrian Handy Signatur is a redirect based method, so:

  1. user gets redirected to the Austrian Handy Signatur page where they have to enter their user and mobile number
  2. Austrian Handy Signatur then asks the user for confirmation on their cellphone
  3. user gets redirected back to the redirectUri specified in the eidEasyClient settings with a token you can use to fetch data
eidEasyClient.identification.atHandy.start({
   redirect: (context) => {
      console.log(context);
      // you can do the redirect here yourself should you wish so
      // window.location.href = context.redirectUrl;
      return {
         data: null,
      };
   },
});

Austrian Handy Signatur identification settings

OptionTypeDefaultDescription
redirectfunctionundefinedYou can use this setting to override the default redirection functionality

Signing Config Reference

Creating the client for signing

const eidEasyClient = window.eidEasyBrowserClient.createClient({
   clientId: '2IaeiZXbcKzlP1KvjZH9ghty2IJKM8Lg', // required
   docId: 'CR1GsqrBICJmJMXTCxM82jxb8MlhLpWTacZARn4o', // required
   countryCode: 'EE', // required
   language: 'et',
   sandbox: true,
});

Client Settings

OptionTypeDefaultDescription
clientIdstringundefinedRequired. Get from id.eideasy.com after signing up.
docIdstringundefinedRequired. The docId of the document you have prepared for signing. You can find more information on file preparation hereopen in new window and the API reference for file preparation hereopen in new window
countryCodestringundefinedRequired. ISO 3166-1 alpha-2open in new window country code
sandboxbooleanfalseWhether to use the sandboxopen in new window mode.
languagestring'en'Two letter ISO 639-1open in new window language code.

Signing with an ID Card

eidEasyClient.signature.idCardSignature.start({
   countryCode: 'EE',
   iframeHolder: document.getElementById('idCardIframeHolder'), // Required. DOM element whose content gets replaced with an iframe (this iframe will be used to get the signing certificates from the id card)
   fail: (error) => {
      // do something with the error
   },
   success: (result) => {
      // do something with the result
   },
   finished: () => {
      // the process has finished, you can do some clean up like hiding a loader here
   },
});

idCard signing settings

OptionTypeDefaultDescription
countryCodestringundefinedRequired. ISO 3166-1 alpha-2open in new window code of the country that issued the id card
iframeHolderDOM elementundefinedRequired. DOM element whose content gets replaced with an iframe (this iframe will be used to get the signing certificates from the id card)
failfunctionundefinedThis function gets called when the signing process failed.
successfunctionundefinedThis function gets called when the signing process succeeds.
finishedfunctionundefinedThis function gets called when the signing process has either failed or succeeded. This means that this function gets called always, no matter the authentication result. For example, it can be useful to hide a loading spinner at the end of the authentication process or to do some other clean up work.

Signing with Smart-ID

eidEasyClient.signature.smartIdSignature.start({
   idcode: '10101010005', // required
   ccountryCode: 'EE', // required
   waitForChallengeCode: false, // required
   started: (result) => {
     if (result.data && result.data.challenge) {
       // do something with the result
       // e.g. display the result.data.challenge code
     }
   },
   onTryComplete: (result) => {
     if (result.data && result.data.challenge) {
       // do something with the result
       // e.g. display the result.data.challenge code
     }
   },
   fail: (error) => {
      // do something with the error
   },
   success: (result) => {
      // do something with the result
   },
   finished: () => {
      // the process has finished, you can do some clean up like hiding a loader here
   },
});

smartId identification settings

OptionTypeDefaultDescription
idcodestringundefinedRequired. End user's personal identification code
waitForChallengeCodebooleantrueRequired. This should be always set to false. Value true is meant for backwards compatibilty for legacy integrations only.
countryCodestringundefinedRequired. ISO 3166-1 alpha-2open in new window code of the country where the user has registered their Smart-ID account
startedfunctionundefinedThis function gets called when the signing process has started. The argument object of this function may contain the security challenge code (response.data.challenge) that the end user sees on their device. In case the signer has not approved the transaciton yet, it contains the session token. If challenge code is present, you should display it in your app so that the user can be sure that they are signing the right document.
onTryCompletefunctionundefinedThis function gets called when the browser client polls for the signign session status. The argument object of this function may contain the security challenge code (response.data.challenge) that the end user sees on their device. In case the signer has not approved the transaciton yet, it contains the session token. If challenge code is present, you should display it in your app so that the user can be sure that they are signing the right document.
failfunctionundefinedThis function gets called when the signing process failed.
successfunctionundefinedThis function gets called when the signing process succeeds.
finishedfunctionundefinedThis function gets called when the signing process has either failed or succeeded. This means that this function gets called always, no matter the authentication result. For example, it can be useful to hide a loading spinner at the end of the authentication process or to do some other clean up work.

Signing with Mobile ID

eidEasyClient.signature.mobileIdSignature.start({
   idcode: '60001019906', // required
   phone: '+37200000766', // required
   ccountryCode: 'EE', // required
   started: (result) => {
      // do something with the result
      // e.g. display the result.data.challenge code
   },
   fail: (error) => {
      // do something with the error
   },
   success: (result) => {
      // do something with the result
   },
   finished: () => {
      // the process has finished, you can do some clean up like hiding a loader here
   },
});

mobileId signing settings

OptionTypeDefaultDescription
idcodestringundefinedRequired. End user's personal identification code
phonestringundefinedRequired. End user's phone number, must have the country codeopen in new window prefixed with a '+' sign, e.g. +37200000766
countryCodestringundefinedRequired. ISO 3166-1 alpha-2open in new window code of the country where the user has registered their Mobile ID account
startedfunctionundefinedThis function gets called when the signing process has started. The argument object of this function contains the security challenge code (response.data.challenge) that the end user sees on their device. You should display this code in your app so that the user can be sure that they are signing the right document.
failfunctionundefinedThis function gets called when the signing process failed.
successfunctionundefinedThis function gets called when the signing process succeeds.
finishedfunctionundefinedThis function gets called when the signing process has either failed or succeeded. This means that this function gets called always, no matter the authentication result. For example, it can be useful to hide a loading spinner at the end of the authentication process or to do some other clean up work.

Signing with eParaksts mobile

eParaksts Mobile is an OAuth2 based method, so the user gets redirected to the eParaksts page where they can complete the signing process.

eidEasyClient.signature.eParakstsMobileSignature.start({
   redirect: (context) => {
      console.log(context);
      // you can do the redirect here yourself should you wish so
      // window.location.href = context.redirectUrl;
      return {
         data: null,
      };
   },
});

eParakstsMobile signing settings

OptionTypeDefaultDescription
redirectfunctionundefinedYou can use this setting to override the default redirection functionality

Signing with ZealiD

ZealId signing is a redirect based method, so the user gets redirected to the Zeal ID view where they can use their smartphone to complete the signing process.

eidEasyClient.signature.zealIdSignature.start({
   ccountryCode: 'EE', // required
   redirect: (context) => {
      console.log(context);
      // you can do the redirect here yourself should you wish so
      // window.location.href = context.redirectUrl;
      return {
         data: null,
      };
   },
});

ZealiD signing settings

OptionTypeDefaultDescription
countryCodestringundefinedRequired. ISO 3166-1 alpha-2open in new window code of the country where the user has registered their Zeal-ID account
redirectfunctionundefinedYou can use this setting to override the default redirection functionality

Signing with Austrian Handy Signatur

Austrian Handy Signatur is a redirect based method, so the user gets redirected to the Austrian Handy Signatur page where they will complete the signing process.

eidEasyClient.signature.atHandySignature.start({
   redirect: (context) => {
      console.log(context);
      // you can do the redirect here yourself should you wish so
      // window.location.href = context.redirectUrl;
      return {
         data: null,
      };
   },
});

Austrian Handy Signatur signing settings

OptionTypeDefaultDescription
redirectfunctionundefinedYou can use this setting to override the default redirection functionality

Signing with Finnish Banks and Mobile ID

This is done through a redirect, so the user gets redirected to a view where they will see all the buttons for all the available Finnish Banks and the Mobile ID button. They then choose their preferred method and complete the signing process.

eidEasyClient.signature.ftnSignature.start({
   redirect: (context) => {
      console.log(context);
      // you can do the redirect here yourself should you wish so
      // window.location.href = context.redirectUrl;
      return {
         data: null,
      };
   },
});

Austrian Handy Signatur signing settings

OptionTypeDefaultDescription
redirectfunctionundefinedYou can use this setting to override the default redirection functionality

Signing with One Time Password (OTP)

With OTP, eID Easy will send the user either an email or sms (depending on with which parameters you initiate the flow) that contains a one time password. You then ask the user to enter that OTP in your application and then provide it to the otpSignature module.

eidEasyClient.signature.otpSignature.start({
   smsToken: '123455',
   emailToken: '873nf7ssorwdm8e',
   fail: (error) => {
      // do something with the error
   },
   success: (result) => {
      // do something with the result
   },
   finished: () => {
      // the process has finished, you can do some clean up like hiding a loader here
   },
});

Austrian Handy Signatur signing settings

OptionTypeDefaultDescription
smsTokenstringundefinedThe token (OTP) that the user receives via sms.
emailTokenstringundefinedThe token (OTP) that the user receives via email.
failfunctionundefinedThis function gets called when the signing process failed.
successfunctionundefinedThis function gets called when the signing process succeeds.
finishedfunctionundefinedThis function gets called when the signing process has either failed or succeeded. This means that this function gets called always, no matter the authentication result. For example, it can be useful to hide a loading spinner at the end of the authentication process or to do some other clean up work.

Signing with Evrotrust

eidEasyClient.signature.evroTrustSignature.start({
   phone: '+37200000766', // required
   ccountryCode: 'EE', // required
   started: (result) => {
      // do something with the result
      // e.g. display the result.data.challenge code
   },
   fail: (error) => {
      // do something with the error
   },
   success: (result) => {
      // do something with the result
   },
   finished: () => {
      // the process has finished, you can do some clean up like hiding a loader here
   },
});

Evrotrust signing settings

OptionTypeDefaultDescription
phonestringundefinedRequired. End user's phone number, must have the country codeopen in new window prefixed with a '+' sign, e.g. +37200000766
countryCodestringundefinedRequired. ISO 3166-1 alpha-2open in new window code of the country where the user has registered their Mobile ID account
startedfunctionundefinedThis function gets called when the signing process has started. The argument object of this function contains the transaction id (response.data.transaction_id) that the end user sees on their device. You should display this code in your app so that the user can be sure that they are signing the right document.
failfunctionundefinedThis function gets called when the signing process failed.
successfunctionundefinedThis function gets called when the signing process succeeds.
finishedfunctionundefinedThis function gets called when the signing process has either failed or succeeded. This means that this function gets called always, no matter the authentication result. For example, it can be useful to hide a loading spinner at the end of the authentication process or to do some other clean up work.
Last Updated: