Skip to main content

Sign API v2

This section details how to integrate with the Norwegian BankID Public Key Infrastructure (PKI) signing implementation using the Sign API v2.

Norwegian BankID PKI signing is the preferred and recommended signing method for Norway, as it provides qualified electronic signatures (QES) and complies with regulatory requirements.

Prerequisites​

  1. Follow the steps on the Initial preparations page to establish a connection with Norwegian BankID.

  2. Before you can start making requests to this API, you need to learn how to connect to it. To do this, follow steps 1-3 in the Connect to Signicat APIs Quick start guide.

Want to learn more?

To learn more about the Signicat Sign API v2, see:

Using the API​

Upload a document, create a document collection and create a signing session​

The basic signature process for Norwegian BankID PKI signing works in the same way as a standard integration, by uploading documents, adding them to document collections and then creating the signing session.

Set up the signing session for Norwegian BankID PKI signing​

To use Norwegian BankID PKI signing, you must set up the signing session as follows:

  1. Specify a signingFlow value. Set this to PKISIGNING.
  2. Specify a vendor value. Set this to NBID.

Combined, the two look as follows in the HTTP POST request to the the Signing sessions endpoint:

"signingSetup": [
  {
    "signingFlow": "PKISIGNING",
    "vendor": "NBID"
  }

UI and technical differences to authentication-based signing​

The signing flow looks similar in the UI to signing with AUTHENTICATION_BASED and selecting only the nbid idp. However, there are significant differences with PKI signing:

  • With PKISIGNING, the system creates signing certificates for eIDAS Common Signing Certificate (CSC) solutions (such as Norwegian BankID and Buypass QES). For Swedish BankID, it uses XML Digital Signature (XMLDSig). Additionally, Dokobit supports qualified electronic signatures (QES).
  • PKISIGNING provides QES-compliant signatures while AUTHENTICATION_BASED does not.
  • When the authentication is complete, the end-user will see a consent screen where they must give their consent before being redirected back to signing interface or to the redirectUri defined in the signing session.

Limitations​

When integrating with Norwegian BankID PKI signing, be aware of the following limitations:

  • We currently only support the Norwegian locale. There is no validation of language settings in the signing session, so ensure your integration requests the appropriate locale (for example nb / nb-NO).
  • We currently do not support referencing the result of a document signed in a previous signing session. To enable the signing of already signed PDFs with Norwegian BankID PKI signing, create a new signing session based on the completed webhook from a previous signing session and use the signed document produced by that session. We are planning to automate this workflow in the future, where a signing session can reference the result document of a previous session via a document ID and document collection ID, rather than requiring a manual process via webhooks.
  • Subject validation in the Sign API v2 currently only supports the national identity number (NIN / fødselsnummer).
  • Norwegian BankID PKI signing requires Level of Assurance (LoA) high.
  • While Norwegian BankID PKI signing provides qualified electronic signatures (QES), generally PKI signing can produce different levels of assurance depending on the eID vendor. Some eIDs produce Qualified Electronic Signatures (QES), while others may produce Advanced Electronic Signatures (AES). Do not assume PKI signing always equals QES. Check the vendor and certificate type for the expected signature level (for example, some Swedish BankID integrations and certain Dokobit eIDs do not produce QES).

Get the result from the signing session​

The signing result is not the usual Signicat PAdES but a Digital Signature Service (DSS)-signed PAdES.

You can retrieve the result as usual by fetching the signing session after completing the signing with an HTTP GET request to the the Signing sessions endpoint. You can find the result in the signatures section of the output object in the signing session:

"output": {
    "signatures": [
      {
        "resultDocumentId": "01999efd-a644-7ca5-8787-47d57eb172f3",
        "signatureType": "PADES"
      }
    ],
    "packages": []
  }

This process happens synchronously, so the result is available as soon as the signing process has been completed.

Additional features​

Subject validation​

You can set up subject validation on the nationalIdentificationNumber value in the signer object of the signing session:

"signer": {
  "nationalIdentificationNumber": "10109001291",
  "validations": [
    "NATIONAL_IDENTIFICATION_NUMBER"
  ]
}

This ensures that the nationalIdentificationNumber provided by the signer during signing matches the one specified in the signing session.

Important

Subject validation in the Sign API v2 currently only supports the national identity number (NIN / fødselsnummer). We are planning to support validation of other attributes. For integrations with other eIDs, you may need to validate on different attributes.


If you specify restrictedUse = "noUse" in the HTTP POST request to the the Signing sessions endpoint, the nationalIdentificationNumber scope is not requested from BankID and the signing certificate will not contain the national identity number. As a result, the creation of the signing session will fail.

Support for multiple signers​

Norwegian BankID PKI signing supports multiple signers on the same document. To use this functionality, follow the steps below:

  1. Create a signing session and sign the document as usual.
  2. Reupload the signed document and add it to a new signing session, which can then be signed by an additional signer.
Mixing signing methods

Note that all signers must use the same signing method. It is not possible to mix signing methods.

The resulting document from this signing session will include all signatures.

API reference​

Explore our Sign API v2 reference documentation to look up all API endpoints and properties as well as view sample requests and responses.

Sign API v2 API reference
Regulatory compliant electronic signatures
On this page