SEID-SDO signing#

SEID-SDO⁠ (opens in a new tab) is an extension of ETSI (the European Telecommunications Standards Institute) CAdES/XAdES standard for signing PDF documents, XML files, and plain text.

Flow#

The BankID SEID-SDO signing flow makes use of the SignDoc API 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 SEID-SDO signing flow, you need to get an access token with the signdoc/read_write scope and use it to create a sign order.

Furthermore, you need to redirect the end user to the BankID authorize endpoint with the sign scope and the sign_id parameter.

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

Steps#

1. 1

   Request an access token with the signdoc/read_write scope using Client Credentials flow.

2. 2

   Create a sign order by uploading the document(s) to be signed to the SignDoc API. You will receive a sign_id.

3. 3

   Redirect the end user to the BankID authorize endpoint with the sign scope and the sign_id parameter.

4. 4

   The end user signs the document(s).

5. 5

   You can check the status of the signing process using the SignDoc API. (Optional)

6. 6

   BankID returns to your callback URL following the standard Authorization Code flow.

7. 7

   Your service exchanges the code for tokens and verifies them.

8. 8

   Download the signed document(s) using the SignDoc API once the signing process is complete.

Sequence diagram#

sequenceDiagram
    actor u as User
    participant Merchant as Your Web App
    participant BankID as BankID
    participant SignDoc as SignDoc API
    u ->> Merchant: Request signing
    Note right of Merchant: (1) Client requests access token
    Merchant->>BankID: POST /token with `signdoc/read_write` scope
    BankID-->>Merchant: Access token
    Note right of Merchant: (2) Client creates sign order
    Merchant-->>SignDoc: POST /signdoc with parameters and document(s) data
    SignDoc-->>Merchant: Sign ID
    Note right of Merchant: (3) Client redirects user to BankID with sign_id
    Merchant->>BankID: GET /authorize?scope=sign&sign_id=xxxx-xxxx&client_id=...
    BankID-->> Merchant: Redirect to callback with code
    Note right of Merchant: (7) Client fetches tokens and verifies
    Merchant->>BankID: POST /token with code
    BankID-->>Merchant: ID tokens
    Note right of Merchant: (8) Client downloads signed document(s)
    Merchant->>SignDoc: DELETE /signdoc?sign_id={sign_id}
    SignDoc-->>Merchant: Signing results and document(s)
    Merchant->>u: Signing complete

API#

Examples#

Create a sign order#

Request#

POST [signdoc-baseurl]/signdoc

You can find the signdoc-baseurl for the appropriate environment in the OpenID Configuration.

Headers#

Authorization: Bearer [access_token]
Content-Type: application/json

Body#

{
  "signProperties": {
    "orderName": "My order name",
    "documentDisplayMode": "interior",
    "showConfirmation": true,
    "showUnderstanding": true,
    "timeoutSeconds": 1800
  },
  "documents": [
    {
      "description": "My PDF document",
      "pdf": "JVBER..."
    },
    {
      "description": "My text",
      "text": "My text to sign..."
    },
    {
      "xml": "<?xml version=\"1.0\" encoding=\"ISO-8859-1\" ?> ...",
      "xls": "<?xml version=\"1.0\" encoding=\"ISO-8859-1\" ?><xsl:stylesheet ..."
    }
  ],
  "resultContent": [
    "basicSignature",
    "documentHash",
    "sdo"
  ]
}

Response#

Status#

201 Created

Headers#

Content-Type: application/json

Body#

{
  "signId": "2a8d69ba-2607-9a1e-9e60-bdb6cc67eacf"
}

The result contains the sign_id reference which is used to identify the sign order.

Check the status of a sign order#

Request#

GET [signdoc-baseurl]/signdoc?sign_id={sign_id}

Headers#

Authorization: Bearer [access_token]
Content-Type: application/json

Response#

Status#

200 OK

Body#

Sign order was found. Returns the order state.

{
    "orderState": "ORDER_RECEIVED"
}

Possible values are:

• ORDER_RECEIVED
• GRABBED_BY_IDP
• USER_SIGNING
• FAILED
• CANCELLED
• SIGN_COMPLETED

Download signing results#

Request#

DELETE [signdoc-baseurl]/signdoc?sign_id={sign_id}

Headers#

Authorization: Bearer [access_token]
Content-Type: application/json

Response#

Status#

200 OK

Body#

{
    "documentHashes": [
        "5OKv0...",
        "l5hoT...",
        "PyLlx..."
    ],
    "merchantSignatures": [
        "MIAGC...",
        "MIAGC...",
        "MIAGC..."
    ],
    "sdos": [
        "PD94b...",
        "PD94b...",
        "PD94b...",
    ],
    "endUserSignatures": [
        "MIAGC...",
        "MIAGC...",
        "MIAGC..."
    ],
    "clientId": "my-oidc-client-id",
    "signId": "2a8d69ba-2607-9a1e-9e60-bdb6cc67eacf",
    "orderState": "SIGN_COMPLETED",
    "orderName": "My order name"
}