# E-Signing with Bankid -no
## Overview
Norwegian eID signing enables users to digitally sign documents using **BankID**, Norway’s national electronic identification system. It provides a secure and legally binding way to authenticate identity and apply digital signatures.
#### Key Features
- **Strong Authentication**: electronic identification
- **Legally Binding Signatures**: Complies with **eIDAS** regulation at the **Substantial** level of assurance.
- **PAdES Format**: The signed documents follow the **PAdES** standard (PDF Advanced Electronic Signatures), ensuring long-term validity and verifiability.
- **Secure Document Review**: Users see the full document before signing.
- **Redirect-Based Flow**: Signing takes place in a hosted flow with success/failure redirects.
- **Audit Trail**: Includes signature metadata and proof of identity verification.
#### Typical Use Cases
- Signing contracts, agreements, and legal forms
- Confirming consent or approvals
- Compliant, identity-backed document workflows
This method is ideal for use cases requiring compliance, security, and a familiar signing experience.
> [!NOTE]
> The BankID Norway Signing service only accepts documents in **PDF format**.
## Signing
### Basic Flow – Single document
1. **Create a signing session** by sending a request to initiate a signing session. The response contains a `id`, which is reused throughout the entire process.
2. **Upload the document** you want signed. In the response, you’ll receive both the id and a file_id. The file_id is required to configure and start the signing process.
3. **Start the signing process** by submitting a request that includes the file_id and optional configuration for how and where the signature should appear on the document (e.g., page number and coordinates). You’ll receive a redirect_url in the response.
4. **Redirect the signer to the redirect_url**. The signer will view the document and sign it using Norwegian BankID. After signing, the user will be redirected to a success or failure URL based on the outcome.
5. **Retrieve the result** by poll the session status using the `id`. Once the session reports `Finished`, the payload contains download links for the signed PDF, ready for retrieval with the appropriate authorization header.
### Multiple Document Signing Flow
1. **Create a signing session** Send a request to initiate a signing session. The response contains a `id`, which is reused throughout the entire process.
2. **Upload the first document**
- Upload the first PDF while passing the `id`. The response returns the same `id` together with the first `file_id`.
- Upload the second PDF in the same way. The response now carries the `id`, `file_id_1`, and `file_id_2`. Keep all three identifiers; both `file_id`s are required for the next step.
3. **Start the signing process** Submit a “start-signing” request that includes the `id`, `file_id_1`, `file_id_2`, and any optional signature-placement data (page numbers and coordinates per document). The service replies with a single `redirect_url`.
4. **Redirect the signer** Send the end-user to the `redirect_url`. The signer will view the documents to be singed. Norwegian BankID guides the signer through both PDFs in sequence, collecting two signatures inside one continuous flow. When finished—or if the user aborts—the browser is sent to either your success or failure return URL.
5. **Retrieve the results** By poll the session status using the `id`. Once the session reports `Finished`, the payload contains download links for the two signed PDFs, ready for retrieval with the appropriate authorization header.
### Error Handling
#### Handling User Cancellation
The end-user can cancel an ongoing authentication or signing session at any time. If this happens, the user will be redirected back to the specified redirect URI provided by the merchant application.
The merchant application must be prepared to handle this callback and respond appropriately.
#### Handling Errors
If an error occurs during an ongoing signing session, the following scenarios may take place:
- The end-user might be shown an error message, often accompanied by an error code, with options to retry or return to the merchant application.
- If the error occurs under the "right conditions," the user can be redirected back to the merchant application, using the same parameters as when a user cancels the session.
- In rare cases, an error other than access_denied might be returned, along with an error_description parameter, depending on the situation.
- In severe cases, the user might be stuck on the BankID platform with no option to return to the merchant application.
## API Overview
### Core Functionalities
#### Environments
We maintain environments you can use:
- **Test (TEST)** environment: [https://test-gateway.zignsec.com/api/v5/openapi/signing/](https://test-gateway.zignsec.com/api/v5/openapi/signing/)
- **Production (PROD)** environment**:** [https://gateway.zignsec.com/api/v5/openapi/signing/](https://gateway.zignsec.com/api/v5/openapi/signing/)
#### Authentication
Each request to our API should be authenticated by sending your subscription key in the “**Zs-Product-Key**” header. Our support creates subscription keys for you (a pair for each environment), and it’s highly recommended to regularly rotate the keys (currently it’s done by sending a support request, but please let us know if you’d like to automate it).
If you need different configurations, it’s possible to register multiple tenants and configure them differently.
### REST API
#### Headers
|Header|Description|Required|
|---|---|---|
|Zs-Product-Key or Authorization|This header parameter is the subscription key you received from ZignSec during the registration process. Example: Authorization: 123456add0cff22873c428e987654321|Yes|
|Content-Type|Specifies the media type of the request body data. Set to application/json if JSON object.|Yes|
#### OpenAPI specification and documentation
##### Live documentation
· [Swagger UI (zignsec.com)](https://test-gateway.zignsec.com/api/v5/openapi/signing/#/)
#### Examples:
**Postman collection:** [Link](https://25357801.fs1.hubspotusercontent-eu1.net/hubfs/25357801/Support%20Files/Postman%20collections/ZignSec%20-%20Signing%20-%20examples.postman_collection.json)
#### API Endpoints
##### Create signing session
**Endpoint:** [https://gateway.zignsec.com/api/v5/sessions/signing/](https://gateway.zignsec.com/api/v5/sessions/signing/)
**Description** Initializes a new signing session. Returns a sessionId used for uploading files and starting the signing process.
##### Upload file
(to be signed)
**Endpoint:** [https://gateway.zignsec.com/api/v5/sessions/signing/{sessionId}/files](https://gateway.zignsec.com/api/v5/sessions/signing/%7bsessionId%7d/files)
**Description:** Uploads a document to be signed in the specified session. The response includes a file_Id which must be used when initiating the signing process.
##### Start signing
Endpoint: [https://gateway.zignsec.com/api/v5/sessions/signing/{sessionId}/sign](https://gateway.zignsec.com/api/v5/sessions/signing/%7bsessionId%7d/sign)
**Description:** Starts the signing process for the uploaded file. You must include the file_Id and optionally provide signature positioning data. The response includes a redirect URL where the user can complete the signing using Norwegian BankID.
##### GET Session details
**Endpoint:** [https://gateway.zignsec.com/api/v5/sessions/signing/{sessionId}](https://gateway.zignsec.com/api/v5/sessions/signing/%7bsessionId%7d/sign)
**Description:** Returns the status and results of the signing session. Includes:
- status: Current session state (e.g., Finished)
- inputFiles: Metadata and URLs for original uploaded files
- signedFiles: Metadata and URLs for signed documents
Example document URL:
https://gateway.zignsec.com/folders/{sessionId}/media/{fileId}
##### GET document
**URL Format (not a REST endpoint):**
[https://gateway.zignsec.com/folders/{sessionId}/media/{fileId}](https://gateway.zignsec.com/folders/%7bsessionId%7d/media/%7bfileId%7d)
**Description:** Downloads a specific original or signed document using the file URL returned in the session result.
**Note:** You **must use** Authorization header with your Subscription key.
#### Cancellation
Presented below is an example of a cancellation response received when the end-user opts to cancel during the signing process:
``` json
{
"id": "67d689c8-8644-41fe-afff-68ad726df08f",
"status": "Cancelled",
"errors": [
{
"code": "CANCELLED_BY_USER",
"description": "Signing cancelled by the end-user",
"statusCode": 410
}
],
"result": {
"inputFiles": [
{
"id": "7b8c01d4-85c3-46c8-9afe-a635431d7b97",
"name": "sample_contract_for_esigning.pdf",
"url": "https://test-gateway.zignsec.com/folders/67d689c8-8644-41fe-afff-68ad726df08f/media/7b8c01d4-85c3-46c8-9afe-a635431d7b97",
"mimeType": "application/pdf",
"md5": "baAE3pP5W2GqXblJ/HRxgA=="
}
],
"signedFiles": [
]
}
}
```
## Testing
Use either of the following test user:
|Name|Personal Number|Entry Passcode|Personal Password|
|---|---|---|---|
|Aksel Herseth|06046517928|otp|qwer1234|
|Ole Bramserud|11920287974|otp|qwer1234|
|Sanna Hansen|12829025475|otp|qwer1234|
|Test Testsen|20872329758|otp|qwer1234|
Or you can request your own BankID test users or test Apps by emailing
[email protected]. Please include the name and fødselsnummer (personal identification number) for each test user. The information should be formatted as follows:
- For characters 'æøå' to be accepted, save file as Unicode-text in Excel .
- Accepted line format is shown below. Use either comma ',' or semicolon ';' as field delimiter.
[Personal ID Number] [BankID Friendly Name] [Last Name] [First Name and possibly Middle Name]
Alternatively, you can create your own test user on the following page: [BankID RA 1.6.6-SNAPSHOT - BankID Norge](https://ra-preprod.bankidnorge.no/#/search/endUser)
For guidance on using the page, refer to the [RA Light User Guide - BankID Norway Developer Portal - Confluence (bankidnorge.no)](https://confluence.bankidnorge.no/confluence/display/DEVPUB/RA+Light+User+Guide)
## Production testing
Currently, there are no test users available for the production environment. Merchants who wish to conduct tests in staging areas using the production environment will need to use real BankID users.