/
Get started with electronic signing
Document toolboxDocument toolbox

Get started with electronic signing

Owned by Kristoffer Kristoffer (Unlicensed)
Last updated: 06 Apr 2020Version comment

Introduction

This page is intended to be a quick-start guide for developers who seek to implement a solution for electronic signing. The page will outline a quick-start guide for using our APIs in this context.

We emphasize that even though this guide contains most of the information needed to set up electronic signing with BankID, you'll need a commercial agreement with one of our partners in order to go live. We encourage to do this as early as possible. For more information on this, check out our getting started guide.


A general note on electronic signing from BankID

Our electronic signing products are, in some sense, an extension of the authentication product.

  • For PAdES and SEID-SDO, the merchant must request an Access token with client credential grant to create and upload the sign order before the user interacts with BankID. After the user has signed, the result is then downloaded from our resource servers.
  • For simple-text signing, the implementation is very similar to that of authentication, with some extra query parameters in the authorize request


Moreover, the implementation guides for PAdES and SEID-SDO are very similar, with the exception of the signdocpades and signdoc APIs, respectively. Note that the products are different. For more on this, check out the Compare e-sign products.


Expiration times

Sign order expiration time

The sign order will expire in 90 seconds after it is created if user signing is not initiated (i.e. request to authorization endpoint).

The timeout for the sign order when user is signing is determined by the timeoutSeconds (default 1800 seconds) specified when the order was uploaded.

After the user has signed the order, the sign order will be valid for another 90 seconds before it expires.

API quick-start guide

Using our APIs for PAdES signing

StepWhat you doEndpointMethodConsiderationsRemarks
1

Get the key properties of the OIDC provider

openid-configurationGET

2Request an Access tokentokenPOSTGrant type client_credentials. Must include the signdoc/read_write scope.The access token is retreived with client credentials grant, i.e. without the involvement of the end user
3Create and upload sign order to the SignDoc resource serversigndocpadesPOSTInclude Access token (2) as Bearer tokenYou'll receive a reference sign_id
4Initiate the signing transaction by redirecting the user to the authorization endpointauthorizeGET

Include the sign scope and sign_id reference as query parameters.

In the callback, make sure to check for error and matching states

Traditional authorization code flow starts.

End user performs the signing process with netcentric BankID. Results are stored in the resource server.

5Exchange authorization code for tokensTokenPOSTCheck matching nonce
6Fetch our public keys and use these to validate token signaturesjwkGET

(opt)Check the status of sign ordersigndocpadesGETInclude Access token (2) as Bearer token. Include sign_id as query parameter.For more details, see Check Status for sign order in signdocpades
7Download sign order results and delete sign ordersigndocpadesDELETEInclude Access token (2) as Bearer token. Include sign_id as query parameter.For more details, see
  • Check Status for sign order, and
  • Delete sign order and download signing results

in signdocpades


Using our APIs for SEID-SDO signing

StepWhat you doEndpointMethodConsiderationsRemarks
1

Get the key properties of the OIDC provider

Openid-configurationGET

2Request an Access tokenTokenPOSTGrant type client_credentials. Must include the signdoc/read_write scope.The access token is retrieved with client credentials grant, i.e. without the involvement of the end user
3Create and upload sign order to the SignDoc resource serversigndocPOSTInclude Access token (2) as Bearer tokenYou'll receive a reference sign_id
4Initiate the signing transaction by redirecting the user to the authorization endpointAuthorizeGET

Include the sign scope and sign_id reference as query parameters.

In the callback, make sure to check for error and matching states

Traditional authorization code flow starts.

End user performs the signing process with netcentric BankID. Results are stored in the resource server.

5Exchange authorization code for tokensTokenPOSTCheck matching nonceThe Access token is to be used to check status (7) and download the result (step 8) from resource server
6Fetch our public keys and use these to validate token signaturesJwkGET

(opt)Check the status of sign ordersigndocGETInclude Access token (2) as Bearer token. Include sign_id as query parameter.For more details, see Check Status for sign order in signdoc
7Download sign order results and delete sign ordersigndocDELETEInclude Access token (2) as Bearer token. Include sign_id as query parameter.For more details, see
  • Check Status for sign order, and
  • Delete sign order and download signing results

in signdoc




Using our APIs for Simple-text signing

Simple-text signing allows the end user to sign a predefined text. The result contains the basic signatures of the merchant and end user, as well as the hash over the received text.

StepWhat you doEndpointMethodConsiderationsRemarks
1

Get the key properties of the OIDC provider

Openid-configurationGET

2Build the authorization URL, and redirect the user to the authorization endpointAuthorizeGET

Include sign scope and sign_txt as query parameters.

In the callback, make sure to check for error and matching states

sign_txt is the text to be signed, and must be base64 encoded.

This is where the end user interacts with BankID.

3Exchange authorization code for tokensTokenPOSTCheck matching nonce

The result is contained in the sign_result claim in the ID token (see example below table).

Also:

4Fetch our public keys and use these to validate token signaturesJwkGET

Example sign_result claim:


"sign_result" : 
{
    "endUser" : "MIAGC...",
    "merchant" : "MIAGC...",
    "hash" : "4oK3g..."
}