Skip to content

Migration Guide

The BankID Server signing and signing using Signdoc over OpenID Connect (OIDC) is being migrated to a new BankID Signing solution by the end of 2025 - as previously outlined in several letters.

This new BankID Signing solution offers a modern user experience with Qualified Person signing, including Qualified Timestamping (QTSA).

This is a breaking change to all previous signing integrations with BankID, including BankID Server and existing OIDC integrations.

Please read this migration guide carefully.

Special notice for those implementing SEID-SDO signing

The SEID-SDO format is not supported in the new BankID Signing solution, except in B2B - for now. We recommend migrating to PAdES signing for documents, CSC Signing API, or B2B for hashes or Permissions API for payment related signing.

Breaking changes

Comparison table

Topic Legacy (Signdoc OIDC / BankID Server) New Signing solution Action Required
Base API URL signdoc-baseurl from Discovery endpoint esign-baseurl from Discovery endpoint Update configuration
scope for Client Credentials signdoc/read_write esign Change scope
Flow type (PAdES) OIDC Authorization Code + Token exchange Direct redirect + callback URI (no OIDC token exchange) Remove token exchange
Signer identity ID Token claims Extract from certificates in signatures / Upcoming signer info data Parse certificate / Signer info
XML / SEID-SDO / text APIs Supported Not supported (except simple sign_txt) Migrate to PAdES / CSC / Permissions
Merchant certificates Long-lived merchant certificates Short-lived session certs issued automatically No action
Trust anchor updates Existing BankID PKI New PKI trust anchors + EU Trust List auto-fetch Update truststore
Visual seal positioning Auto or default Not automatic. Use default (0,0) or set position. Set parameter dynamically. See field documentation
iFrame embedding Possible Not supported Redesign integration
Signature level AdES-LT/T AdES-LTA ( with extendToLta) Validate archival policy
Identity prefill (login_hint) Supported Not yet (roadmap) Remove usage
Merchant only signing Supported Supported. See B2B signing Migrate to B2B

Convert API

  • New Base URL for API calls. See esign-baseurl in OpenID Configuration

  • Changes to error messages from the Convert API.

SEID-SDO signing

Text signing

Simple text signing using sign_txt parameter

  • Unchanged - still OIDC Authorization Code flow with sign results in ID Token.

XML signing

PAdES signing

  • New Base URL for API calls. See esign-baseurl in OpenID Configuration

  • New Certificate trust. Trust anchors will need to be updated. Merchants would need to add the new PKI to their truststore. This process is automated for software (like Adobe Reader) that routinely fetches trust anchors from EU Trust List, but systems would most likely need manual updating.

  • No more signatures with BankID merchant certificates. Instead short lived certificates are generated per session.

  • There is no SEID profile. Meaning no NNIN via OCSP, but NNIN in cert. Minor changes to certificate contents (subject) etc.

  • We now deliver AdES-LTA when extendToLTA parameter in a sign order is used, compared to AdES-LT/T that is currently provided

  • The service does not auto-adjust the positioning of the visual signature seal. Default position is 0,0. The parameter endUserSealPos can be used when submitting a sign order to set position.

  • No iframe support.

  • The flow is no longer a OpenID Connect Authorization Code flow request.

  • There is no Token Request or ID Token with signer info after signing. Get signer info from the certificate data in the signed documents. NOTE: We are planning to add support for dedicated signer info in Signing API.

  • Login Hint to prefill NNIN is currently not supported, but support is on the roadmap.

  • Changes to error messages from the Signing API.

Merchant only signing using BankID Server

  • BankID Server SDK can no longer be used, this feature is offered in new B2B solution.

  • Requires DPOP and Private Key JWT

  • Supports SEID-SDO.

Migrating

Convert API

  1. Change Base URL in API calls from signdoc-baseurl to esign-baseurl.
  2. (Recommended) change scope from signdoc/read_write to esign for Client Credentials Access Token.
  3. (Recommended) check if the implementation depends on error messages from the Convert API - those change with the new solution.

See API documentation under Convert API v1.

PAdES signing

We recommend to move directly to PAdES Signing API v1 to be future-proof. This streamlined API-version omits the legacy parameters and adds several new features such as:

  • Allowing to pass a callback URL to control where the end-user ends up after signing. Otherwise the user will close the window after signing.
  • The option to add an LTA timestamp to the signed document.
  • Option to receive signer info together with the signed documents (coming soon).

From BankID Server

If you are migrating from BankID Server, you are no longer depending on the BankID Server SDK. Instead, you implement the flow described in the PAdES documentation.

From Signdoc over OpenID Connect

If you are migrating from Signdoc and the OpenID Connect integration, you need to make some minor changes to the flow and API integration.

The full documentation is available here, but we have outlined below some of the steps you must take:

  1. When asking for Client Credentials access token to perform API requests, change scope from signdoc/read_write to esign.
  2. Change Base URL in API calls from signdoc-baseurl to esign-baseurl.
  3. Make existing call to create Sign Order to the new v1 API endpoint (as before) with additional parameters:
  4. (Optional) Add signProperties.redirectUrl with your callback URL for a redirect after signing. You may add your state information to redirectUrl here, e.g. https://example.org/callback?state=1234. The sign_id and a status parameter will also be added automatically.
  5. Take sign_id from the result from (3), and redirect end-user to new Signing UI (What You See Is What You Sign) endpoint.
  6. Test: https://web.preprod.esign-stoetest.cloud/${sign_id}
  7. Prod: https://web.esign-stoe.cloud/${sign_id}
  8. NOTE: This is not an OIDC Authorization Code flow.
  9. The end user signs the document(s).
  10. (Optional) You can check the status of the signing process using the Signing API.
  11. After signing, the end-user will be redirected to the callback URL registered in (3).
  12. Remove Token Exchange call as this is not an OIDC Authorization Code flow.
  13. NOTE: This means there are no ID token identifying the end-user. See next step.
  14. Keep existing call to download Signing results from Signing API. The signing results contains the signed documents. The signer info will soon be available in a separate data field. For now, read the certificate data in the signatures (recommended).

Other things to keep in mind:

  • Check the API documentation which results the implementation expects from the API - some legacy parameters are still accepted but ignored and some no longer supported result elements are returned empty.
  • Check if your implementation depends on error messages from the API - those may change with the new solution.

Sequence diagram

sequenceDiagram
    actor u as User
    participant Merchant as Your Web App
    participant BankID as BankID OIDC
    participant MBE as Signing API
    participant FE as Signing UI
    u ->> Merchant: Request signing
    Note right of Merchant: (1) Client requests access token
    Merchant->>BankID: POST /token with `esign` scope
    BankID-->>Merchant: Access token
    Note right of Merchant: (2) Client creates sign order
    Merchant-->>MBE: POST /signdoc/pades with parameters and document(s) data
    MBE-->>Merchant: Sign ID
    Note right of Merchant: (3) Client redirects user to WYSIWYS UI with sign_id
    Merchant->>FE: e.g. https://web.preprod.esign-stoetest.cloud/<SIGN_ID>
    FE-->> Merchant: Redirect to redirect url (optional, if parameter set)
    Note right of Merchant: (8) Client downloads signed document(s)
    Merchant->>MBE: DELETE /signdoc/pades?sign_id={sign_id}
    MBE-->>Merchant: Signing results and document(s)
    Merchant->>u: Signing complete

Checklist

  • Obtain new or updated client credentials authorized for scope esign.
  • Update base URLs in configuration (esign-baseurl).
  • Remove legacy OIDC Authorization Code + Token Exchange step.
  • Implement new sign order creation with endUserSealPos and optional redirectUrl.
  • Implement WYSIWYS redirect.
  • Parse session certificate for signer identity (until signer info field is released).
  • Update truststore with new BankID E-sign PKI anchors.
  • Verify handling of new error codes and map legacy fallbacks.
  • Validate that iframe embedding is removed and UX flows are full-page redirect or popup.
  • Add archival validation to confirm AdES-LTA presence.