SEID-SDO signing¶

SEID-SDO 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¶

Request an access token with the signdoc/read_write scope using Client Credentials flow.
Create a sign order by uploading the document(s) to be signed to the SignDoc API. You will receive a sign_id.
Redirect the end user to the BankID authorize endpoint with the sign scope and the sign_id parameter.
The end user signs the document(s).
You can check the status of the signing process using the SignDoc API. (Optional)
BankID returns to your callback URL following the standard Authorization Code flow.
Your service exchanges the code for tokens and verifies them.
Download the signed document(s) using the SignDoc API once the signing process is complete.

Warning

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

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¶

Note

You will always find the up-to-date URL for the SignDoc API in the OpenID Configuration - as signdoc-baseurl.

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"
}