For the complete documentation index, see llms.txt. You can also append .md to any page URL to get its markdown version.
Skip to main content
For the complete documentation index, see llms.txt.

For the complete documentation index, see llms.txt

Sign API for Norwegian BankID

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. For the complete documentation index, see llms.txt

    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:

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).
  • Subject validation in the Sign API v2 currently only supports the national identity number (NIN / fødselsnummer).
  • We do not support login hints or prefilled user information.
  • 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).

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 Signing sessions endpoint:

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

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 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 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 using a flexible, unordered signing workflow with an automatic locking mechanism. See the section on Flexible, unordered signing with locking mechanism in our Sign API v2 integration guide for details on how to use this feature.

Retrieving the final document​

The final result is a single, valid DSS-signed PAdES document containing the complete chain of signatures. When all parties have signed, retrieve the final PAdES from the parent document collection:

  1. Get the document collection by its ID by making an HTTP GET request to the Document collections endpoint, using the collectionId you used for all the signing sessions.
  2. Extract the resultDocumentId from the response (which points to the final PAdES containing all signatures).
  3. Download the final signed document by making an HTTP GET request to the Documents endpoint using the resultDocumentId.
Mixing signing methods

All signers must use the same signing method. It is not possible to mix signing methods (e.g., combining Norwegian BankID PKI signing and authentication-based signing) within the same document collection.

Merchant signing​

Merchant signing, also known as business-to-business (B2B) signing or sealing, allows you to sign documents using a merchant certificate. This section details how to use merchant signing with Norwegian BankID.

For more information on how merchant signing works, see our Merchant signing guide.

Note

Norwegian BankID for merchant signing provides an Advanced Electronic Signature (AES).

Configuration and setup​

To use merchant signing with Norwegian BankID, the following configuration is required:

  • Sandbox: A default client is pre-configured in our sandbox environment, so you can start testing immediately without any additional setup.
  • Production: You must have a dedicated Norwegian BankID B2B client. This is separate from the client used for standard end-user signing. To have this set up for production, contact us by creating a support ticket in the Signicat Dashboard.

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