Skip to content

BankID Signing API introduction

PAdES signing

BankID Signing offers a PAdES (PDF Advanced Electronic Signatures) signing solution that allows you to sign PDF documents for long-term validation.

  • Offers support for signing PDF documents with Qualified Electronic Signatures (QES).
  • Combines a versatile API with a modern graphical user interface to set up sign orders and guide your customers through the process.
  • Supports multiple end user signatures through serial signing where the output from one signing session is used as input for the next
  • Allows you to configure the visible seal applied to the PDF document after signing.
  • Allows addition of a Qualified Timestamp (QTS) with qualified timestamp certificates to the documents.

Flow

The BankID Signing API allows to:

  • create a sign order by uploading the document(s) to be signed
  • check the status of the signing process
  • download the signed document(s) after the signing process is complete

In order to use the PAdES signing flow, you need to get an access token with the esign scope and use it to create a sign order.

Furthermore, you need to redirect the end user to the BankID Signing UI endpoint with the sign_id parameter (e.g. https://web.preprod.esign-stoetest.cloud/en/<SIGN_ID>).

Finally, you can download the signed document(s) using the SignDoc API once the signing process is complete.

API versions

There are currently two different versions of BankID Signing API: V0 and V1

  • V0 is a backward compatible API for the BankID OIDC SignDoc API with as few changes as possible to make switching over easier.
  • V1 is a modernized, slightly more compact variant that offers all our new features and more information.

We recommend using V1, especially if you are starting fresh or coming from signing in BankID COI. All future new features will only be available in V1 or higher.

Steps

  1. Request an access token with the esign scope using Client Credentials flow.
  2. Create a sign order by uploading the document(s) to be signed to the BankID Signing API (POST). You will receive a sign_id.
  3. Redirect the end user to the BankID Signing UI endpoint with the sign_id parameter.
  4. The end user signs the document(s).
  5. You can check the status of the signing process using the BankID Signing API (GET). (Optional)
  6. You can set a parameter to have BankID Signing redirect the user to your callback URL. Otherwise, the user can just close the browser window after signing (default behavior).
  7. Download the signed document(s) using the SignDoc API once the signing process is complete (DELETE).

Warning

The sign order is only valid for 90 seconds before signing starts, and 90 seconds after signing ends.

Sequence diagram

```mermaid
sequenceDiagram
    actor u as User
    participant Merchant as Your Web App
    participant BankID as BankID
    participant MBE as BankID Signing API
    participant FE as BankID 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 BankID Signing UI with sign_id
    Merchant->>FE: e.g. https://web-test.preprod.esign-stoetest.cloud/en/<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
```

API

Have a look at the OpenAPI specifications to learn more about all the parameters and return values: