Full flow SEID-SDO API and implementation guide
- Jan Åge Lavik
- Markdown Macros for Confluence
Full flow SEID-SDO API and implementation guide.
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
See signdoc for API documentation.
Claims
The following table shows the supported claims in response from the sign service after a SEID-SDO sign session is completed.
| Claim | Example | Result specifier | Description |
|---|---|---|---|
documentHashes |
| documentHash | Array of hashes over the documents to be signed in the same order as the documents in the signing order |
sdos | "sdos": [ "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZ......"] | sdo | The SEID-SDO represented as base64 (unpack to UTF-8), one for each document |
merchantSignatures | "merchantSignatures": [ "MIAGCSqGSIb3DQEHAqCAMIACAQExDzANB...."] | basicSignature | The merchant signature, one for each document |
endUserSignatures | "endUserSignatures": [ "MIAGCSqGSIb3DQEHAqCAMIACAQExDTALBAA....."] | basicSignature | The end user signature, one for each document |
signId | "910bd95b-41c0-4b6d-ae3f-d9458110d12a" | The sign_id used | |
clientId | "oidc-testclient" | The OIDC client used | |
orderState | "SIGN_COMPLETED" | Current order state | |
orderName | "Overlay-example" | Name of order |
Step-by-step
| Step | What you do | Endpoint | Method | Considerations | Remarks |
|---|---|---|---|---|---|
| 1 | Get the key properties of the OIDC provider | Openid-configuration | GET | ||
| 2 | Request an Access token | Token | POST | Grant 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 |
| 3 | Create and upload sign order to the SignDoc resource server | signdoc | POST | Include Access token (2) as Bearer token | You'll receive a reference sign_id |
| 4 | Initiate the signing transaction by redirecting the user to the authorization endpoint | Authorize | GET | Include the 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. |
| 5 | Exchange authorization code for tokens | Token | POST | Check matching nonce | The Access token is to be used to check status (7) and download the result (step 8) from resource server |
| 6 | Fetch our public keys and use these to validate token signatures | Jwk | GET | ||
| 7* | Check the status of sign order | signdoc | GET | Include Access token (2) as Bearer token. Include sign_id as query parameter. | *Can be skipped if The merchant should poll this endpoint for the active signing session and update the status in their backend. This should be done until For more details, see Check Status for sign order in the SEID-SDO documentation. |
| 8 | Download sign order results and delete sign order | signdoc | DELETE | Include Access token (2) as Bearer token. Include sign_id as query parameter. | Should be called when end-user is redirect back to the merchant or if polling returns the
For more details, see
in signdoc |
Note that the sign order is deleted regardless of the state of the sign order.