OTPs in detail

An OTP (One-Time Password) is often used in a digital signature process to provide an extra layer of security and ensure that only the authorised user can perform the signing action.

In Web Trust we support two types of OTP:

  • via sms

  • via email

To configure a signature to use the OTP, we have to specify the parameter otp in the signature creation body, for example

{ // Signature creation payload
  ...

  otp: {
    sms: "+393455677890",
    email: "myemail@server.com"
  },

  ...
}

In this example the system will first verify the phone number specified in sms and if it’s correct and the country code is supported, then the sms will be used; otherwise the email will be used.

The SMS property

When specifying a phone number, we can use a configuration object instead of the string with the phone number. This object has the properties: phoneNumber and skipWhenNoGeoPermission. skipWhenNoGeoPermission is used to ignore the OTP altogether in the case the country code specified in the phoneNumber is not supported by Web Trust.

This is an example of configuration using an object instead of a string.

{ // Signature creation payload
  ...

  otp: {
    sms: {
      phoneNumber: "+9412345435",
      skipWhenNoGeoPermission: true
    }
  },

  ...
}

List of supported country codes

  • Canary Islands (+3491)

  • Finland/Aland Islands (+358)

  • Portugal (+351)

  • Ireland (+353)

  • Slovenia (+386)

  • Serbia (+381)

  • San Marino (+378)

  • Malta (+356)

  • Montenegro (+382)

  • Moldova (+373)

  • Luxembourg (+352)

  • Slovakia (+421)

  • Ukraine (+380)

  • Kosovo (+383)

  • Monaco (+377)

  • Vatican City (+379)

  • Latvia (+371)

  • Republic of North Macedonia (+389)

  • Liechtenstein (+423)

  • Andorra (+376)

  • Bosnia and Herzegovina (+387)

  • Estonia (+372)

  • Czech Republic (+420) -- T-Mobile and O2 are not supported

  • Lithuania (+370)

  • Gibraltar (+350)

  • Cyprus (+357)

  • Faroe Islands (+298)

  • Albania (+355)

  • Iceland (+354)

  • Croatia (+385)

  • Bulgaria (+359)

  • Netherlands (+31)

  • Sweden (+46)

  • Poland (+48)

  • Austria (+43)

  • Denmark (+45)

  • Spain (+34)

  • Italy (+39)

  • Germany (+49)

  • France (+33)

  • United Kingdom (+44)

  • Romania (+40) -- Telekom Romania is not supported

  • Norway (+47)

  • Singapore (+65)

  • Greece (+30)

  • Hungary (+36)

  • Belgium (+32)

  • Switzerland (+41)

  • Isle of Man (+44)

  • Guernsey/Jersey (+44)

  • United States (+1)

  • Canada (+1)

The SMS message can be customised prior moderation; see here

The email property

Alternatively, we could send the OTP via email. As in the SMS case, we could specify a configuration object instead of a string when defining the sms property. This object is composed of the properties: to and emailCustomisation.

emailCustomisation is also an object composed of the following properties:

  • subject: email’s subject

  • preOTPText: text that appears immediately before the OTP code in the email body

  • applicationName: text that will be used in the from email address together with no-reply@kopjra.com and below the logo in the email body.

  • logoUrl⁣: A publicly accessible URL that points to an image that will be used in the body of the email.

Here is an example:

{ // Signature creation payload
  ...

  otp: {
    email: {
      to: "my-email@server.com",
      emailCustomisation: {
        subject: "Please check the OTP inside",
        preOTPText: "The following is the OTP i just sent you:",
        applicationName: "My company",
        logoUrl: "https://public.my-company.com/logo.png"
      }
    }
  }

  ...
}

The properties of emailCustomisation are all optional, so you can customise only parts of the email.

This same customisation can be done at an Archetype level; see this.