openapi: 3.0.3 info: title: BankID Signing Pades V1 description: BankID Signing Pades V1 version: 1.0.0 servers: - url: "https://api.preprod.esign-stoetest.cloud" description: "Public testing environment" - url: "https://api.esign-stoe.cloud" description: "Production" components: securitySchemes: bearerAuth: type: oauth2 flows: clientCredentials: tokenUrl: https://auth.current.bankid.no/auth/realms/current/protocol/openid-connect/token scopes: esign: Standard "umbrella” scope that can cover qualified + TSA esign/qualified: Qualified signatures esign/nnin: Norwegian National Identity Number signdoc/read_write: Grants API Access # schemas: # SignerInfo: # type: object # description: Signer information (NOT IMPLEMENTED YET). Schema reserved for future use. # properties: # name: # type: string # description: Full name of the signer # family_name: # type: string # description: Surname (last name) of the signer # given_name: # type: string # description: Given name (first name) of the signer # nnin_altsub: # type: string # description: National identity number of the signer # nnin: # type: string # description: National identity number of the signer # country: # type: string # description: Country of the signer # birthdate: # type: string # description: Date of birth of the signer # required: # - name # - family_name # - given_name parameters: signId: name: sign_id description: The sign_id that was return when uploading the signing order. in: query required: true schema: type: string maxLength: 50 responses: C-204: description: Sign order was not found. This could be caused by timeout or an invalid sign_id. C-400-Easy: description: The query parameter sign_id was not provided. content: application/json: schema: type: string C-403: description: Access token is invalid or missing. content: application/json: schema: type: string C-404: description: Sign order was not found. This could be caused by timeout or an invalid sign_id. security: - bearerAuth: [] paths: /v1/signdoc/pades: post: summary: Upload sign order to BankID Signing resource server operationId: post-pades security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: signProperties: type: object properties: orderName: type: string description: Order name. maxLength: 50 timeoutSeconds: type: integer description: Timeout in seconds for end user signing. Sign order will get orderState TIMED_OUT after expiry. default: 1800 redirectUrl: type: string format: uri description: Endpoint to redirect signer to after signing. continueButtonTargetText: type: string maxLength: 20 description: Text shown as target/subject on the "Continue"-button (as in "Continue to ") in the finish/download page. merchantWorkflowState: type: string default: NO_WORKFLOW description: Existence and state of the merchant workflow this sign order belongs to. enum: - NO_WORKFLOW - WORKFLOW_ACTIVE requestCallback: type: boolean default: false description: If true, WYSIWYS will send a callback to the redirectUrl when the signing process is completed. Must not be set without redirectUrl also being set. required: - orderName padesSignProperties: type: object properties: addVisualSeals: type: boolean description: If true, add visual signature seals to PDF. extendToLT: type: boolean default: false description: Attempts to extend signature of all documents to PAdES-B-LT. All revocation data (CRL) for the latest signature will be added. For existing non-LT signatures a timestamp will also be added. Note that this is cannot be used together with 'extendToLTA'. extendToLTA: type: boolean default: false description: Attempts to extend signature of all documents to PAdES-B-LTA (Long Term Archive) by adding a trusted timestamp and all relevant validation material. Note that this is cannot be used together with 'extendToLT'. useConversion: type: boolean default: false description: If true, all PDFs will be validated for standard conformance and converted to standard if needed. As long as set to false documents will be taken as-is when attempting to sign. This flag replaces the implicit conversion flag by setting the 'pdfSpec'-attribute that is used in the V0 and legacy APIs. Note that conversion can not be used with already signed docuemnts. required: - addVisualSeals documents: type: array description: JSON array of documents to be signed (minimum one). Be aware that very large PDF files, typically files with a large number of images, might give a less than optimal user experience due to the document processing time. minItems: 1 maxItems: 30 items: type: object properties: description: type: string description: Description of document. Displayed to end user in client. If not specified, orderName from signProperties will be used combined with a number, i.e. "My order name - 1" for the first document. maxLength: 100 pdf: type: string description: Base64 encoded PDF # 40 MB maxLength: 41943040 endUserOnly: type: boolean description: Set to true if only the end user signature is desired. default: false endUserSealPos: type: object description: Specifies the position of signature seal in PDF. The seal will be positioned according to the x and y coordinates (in points) with origin in the upper left corner. properties: x: type: number description: Horizontal positioning of seal. y: type: number description: Vertical positioning of seal. page: type: integer description: Page number to place seal. pdfSpec: type: string description: Defines the targeted PDF specification for conversion. Currently only PDFA_2B is supported. enum: - PDFA_2B followRotation: type: boolean description: If true, the positioning of the signature seal will follow the rotation of the page. If false, the signature seal will be aligned to the view of the PDF. default: true required: - pdf resultContent: type: object description: Claims of additional content to be returned in the signing results. properties: requestSignerInfo: type: boolean default: false description: Request a JSON Web Token containing verified signer information. The JWT can be validated using the public key from the /jwks endpoint. required: - signProperties - padesSignProperties - documents responses: "201": description: Successfully uploaded PAdES sign order content: application/json: schema: type: object properties: sign_id: type: string conversionResults: type: array description: Response if pdfSpec is used items: type: object properties: conversionId: type: string description: type: string converted: type: boolean conversionErrors: type: array items: type: string conversionWarnings: type: array items: type: string "400": description: Could not create order due to error in request. See the "errors"-array in the response for details. Note - 400-responses created because of syntactical errors can be in string-only format. content: application/json: schema: type: object properties: errors: type: array items: type: string conversionResults: type: array description: Response if pdfSpec is used items: type: object properties: conversionId: type: string description: type: string converted: type: boolean conversionErrors: type: array items: type: string conversionWarnings: type: array items: type: string "403": $ref: "#/components/responses/C-403" get: summary: Check status of sign order operationId: get-pades security: - bearerAuth: [] parameters: - $ref: "#/components/parameters/signId" responses: "200": description: Sign order was found. Returns the order state. content: application/json: schema: type: object properties: orderState: type: string enum: - ORDER_RECEIVED - USER_SIGNING - REJECTED # replaces CANCELLED - FAILED - TIMED_OUT - CANCELLED # deprecated - will be treated as REJECTED for compatibility - SIGN_COMPLETED "204": $ref: "#/components/responses/C-204" "400": $ref: "#/components/responses/C-400-Easy" "403": $ref: "#/components/responses/C-403" "404": $ref: "#/components/responses/C-404" delete: summary: Delete sign order and download signing results operationId: delete-pades security: - bearerAuth: [] parameters: - $ref: "#/components/parameters/signId" responses: "200": description: Sign order was found. The claims returned in the signing results depends on the values pass to the resultContent array when creating the order. If order is not completed, i.e. order state is not SIGN_COMPLETED, the signing results will be an empty array. content: application/json: schema: type: object properties: signingResults: type: array items: type: object properties: signedDocumentSha256: type: string description: Hash over the signed document (base64 encoded). padesSignedPdf: type: string description: The signed pdf as a base64 encoded text string. description: type: string description: Description of the document unsignedDocumentSha256: type: string description: Hash (Hex-encoded) over the original document (base64 encoded form). signId: type: string description: The sign_id reference orderName: type: string description: Name of the order orderState: type: string description: The current order state signerInfo: type: string description: JSON Web Token containing verified signer information extracted from the signing certificate. Only present if requestSignerInfo is set to true in resultContent. Validate using the public key from the /jwks endpoint. format: jwt example: "eyJhbGciOi..." "204": $ref: "#/components/responses/C-204" "400": $ref: "#/components/responses/C-400-Easy" "403": $ref: "#/components/responses/C-403" "404": $ref: "#/components/responses/C-404"