openapi: 3.0.3 info: title: SK-ID MFA description: 'The SK-ID integration provide functionality for clients to initiate and confirm documents signing' version: '1' servers: - url: 'https://api.plumery.com' description: Live Server security: - cookieAuth: [ ] tags: - name: SK-ID Smart-ID signing description: API for signing documents with Smart-ID - name: SK-ID Mobile-ID signing description: API for signing documents with Mobile-ID paths: '/internal/v1/mfa/sk-id/smart-id/signature/{challengeId}:initiate': post: tags: - SK-ID Smart-ID signing summary: Initiate Smart-ID signing challenge x-plumery-audit-action-type: SkIdSmartIdSigningChallengeInitiated x-plumery-audit-action-name: Smart-ID Signing Challenge Initiated x-plumery-audit-action-description: Smart-ID signing challenge was initiated to authorize some action description: |- Initiates SK-ID Smart-ID signing challenge. This will initiate a process of document signing and return verification code which end-user should confirm in SK-ID Smart-ID application. operationId: initiateSkIdSmartIdSigningChallenge parameters: - $ref: '#/components/parameters/challengeId' responses: '202': headers: Location: schema: type: string example: '/internal/v1/mfa/sk-id/smart-id/signature/{challengeId}:confirm' description: URL to confirm signing challenge. description: SK-ID Smart-ID signing challenge request accepted. content: application/json: schema: $ref: "#/components/schemas/InitiateSigningResponse" '400': description: Signing session was already initiated for the challenge. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorised. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: ChallengeId not found or expired. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' default: description: Unexpected error x-internal: false '/internal/v1/mfa/sk-id/smart-id/signature/{challengeId}:confirm': post: tags: - SK-ID Smart-ID signing summary: Confirm SK-ID Smart-ID signing challenge x-plumery-audit-action-type: SkIdSmartIdSigningChallengeConfirmed x-plumery-audit-action-name: Smart-ID Signing Challenge Confirmed x-plumery-audit-action-description: Smart-ID signing challenge was successfully confirmed description: |- Confirms SK-ID Smart-ID signing challenge. This will trigger notification to user's phone with prompt to confirm signing. Then get the signature, verify it and save. Note: This endpoint should be polled repeatedly whenever a SK_ID_SIGNING_NOT_YET_COMPLETED_EXCEPTION error response is returned. Continue polling until either: - a successful response (204 No Content) is received, indicating signing has completed, or - a different error response is returned, which means the signing process has failed and polling must stop. operationId: confirmSkIdSmartIdSigningChallenge parameters: - $ref: '#/components/parameters/challengeId' responses: '204': description: Signature is obtained and saved. Unauthorised operation is allowed. '400': description: Signing already confirmed or Signing session not initiated. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorised. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: ChallengeId not found or expired. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' default: description: Unexpected error x-internal: false '/internal/v1/mfa/sk-id/mobile-id/signature/{challengeId}:initiate': post: tags: - SK-ID Mobile-ID signing summary: Initiate Mobile-ID signing challenge x-plumery-audit-action-type: SkIdMobileIdSigningChallengeInitiated x-plumery-audit-action-name: Mobile-ID Signing Challenge Initiated x-plumery-audit-action-description: Mobile-ID signing challenge was initiated to authorize some action description: |- Initiates SK-ID Mobile-ID signing challenge. This will initiate a process of document signing and return verification code which end-user should confirm in SK-ID application. operationId: initiateSkIdMobileIdSigningChallenge parameters: - $ref: '#/components/parameters/challengeId' responses: '202': headers: Location: schema: type: string example: '/internal/v1/mfa/sk-id/mobile-id/signature/{challengeId}:confirm' description: URL to confirm signing challenge. description: SK-ID Mobile-ID signing challenge request accepted. content: application/json: schema: $ref: "#/components/schemas/InitiateSigningResponse" '400': description: Signing session was already initiated for the challenge. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorised. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: ChallengeId not found or expired. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' default: description: Unexpected error x-internal: false '/internal/v1/mfa/sk-id/mobile-id/signature/{challengeId}:confirm': post: tags: - SK-ID Mobile-ID signing summary: Confirm SK-ID Mobile-ID signing challenge x-plumery-audit-action-type: SkIdMobileIdSigningChallengeConfirmed x-plumery-audit-action-name: Mobile-ID Signing Challenge Confirmed x-plumery-audit-action-description: Mobile-ID signing challenge was successfully confirmed description: |- Confirms SK-ID Mobile-ID signing challenge. This will trigger notification to user's phone with prompt to confirm signing. Then get the signature, verify it and save. Note: This endpoint should be polled repeatedly whenever a SK_ID_SIGNING_NOT_YET_COMPLETED_EXCEPTION error response is returned. Continue polling until either: - a successful response (204 No Content) is received, indicating signing has completed, or - a different error response is returned, which means the signing process has failed and polling must stop. operationId: confirmSkIdMobileIdSigningChallenge parameters: - $ref: '#/components/parameters/challengeId' responses: '204': description: Signature is obtained and saved. Unauthorised operation is allowed. '400': description: Signing already confirmed or signing session not initiated. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorised. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: ChallengeId not found or expired. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' default: description: Unexpected error x-internal: false components: schemas: ErrorCode: enum: - 'urn:plmr:mfa:sk-id:api:USER_NOT_FOUND' - 'urn:plmr:mfa:sk-id:api:USER_MISSING_REQUIRED_DETAILS' - 'urn:plmr:mfa:sk-id:api:SK_ID_COMMUNICATION_FAILURE' - 'urn:plmr:mfa:sk-id:api:STEP_UP_REQUEST_CONTEXT_NOT_FOUND' - 'urn:plmr:mfa:sk-id:api:SIGNING_CONFIRMATION_MESSAGE_TEMPLATE_NOT_FOUND' - 'urn:plmr:mfa:sk-id:api:SIGNING_CONFIRMATION_MESSAGE_TEMPLATE_EVALUATION_FAILED' - 'urn:plmr:mfa:sk-id:api:SIGNING_SESSION_NOT_FOUND' - 'urn:plmr:mfa:sk-id:api:SIGNING_SESSION_ALREADY_INITIATED' - 'urn:plmr:mfa:sk-id:api:SK_ID_WRONG_VERIFICATION_CODE' - 'urn:plmr:mfa:sk-id:api:SK_ID_USER_REFUSED' - 'urn:plmr:mfa:sk-id:api:SK_ID_TIMEOUT' - 'urn:plmr:mfa:sk-id:api:SK_ID_USER_NOT_MID_CLIENT' - 'urn:plmr:mfa:sk-id:api:SK_ID_USER_CANCELED' - 'urn:plmr:mfa:sk-id:api:SK_ID_DOCUMENT_UNUSABLE' - 'urn:plmr:mfa:sk-id:api:SK_ID_PHONE_ABSENT' - 'urn:plmr:mfa:sk-id:api:SK_ID_DELIVERY_ERROR' - 'urn:plmr:mfa:sk-id:api:SK_ID_SIM_ERROR' - 'urn:plmr:mfa:sk-id:api:SK_ID_SIGNATURE_HASH_MISMATCH' - 'urn:plmr:mfa:sk-id:api:SK_ID_INTERACTION_NOT_SUPPORTED' - 'urn:plmr:mfa:sk-id:api:SK_ID_USER_CANCELED_VERIFICATION_CODE_AND_MESSAGE' - 'urn:plmr:mfa:sk-id:api:SK_ID_USER_DOES_NOT_EXISTS' - 'urn:plmr:mfa:sk-id:api:USER_ID_DOES_NOT_MATCH_WITH_CHALLENGE_SUBJECT_USER_ID' - 'urn:plmr:mfa:sk-id:api:SK_ID_UNKNOWN_RESPONSE' - 'urn:plmr:mfa:sk-id:api:SK_ID_SIGNATURE_VERIFICATION_FAILURE' - 'urn:plmr:mfa:sk-id:api:SK_ID_SIGNING_INITIATION_FAILURE' - 'urn:plmr:mfa:sk-id:api:SK_ID_SIGNING_NOT_YET_COMPLETED_EXCEPTION' - 'urn:plmr:mfa:sk-id:api:NOT_SUPPORTED_SK_ID_TYPE' - 'urn:plmr:mfa:sk-id:api:INVALID_PERSONAL_ID' - 'urn:plmr:mfa:sk-id:api:INVALID_PHONE_NUMBER' - 'urn:plmr:mfa:sk-id:api:BAD_REQUEST' type: string example: 'urn:plmr:mfa:sk-id:api:USER_NOT_FOUND' FieldErrorCode: enum: - 'urn:plmr:mfa:sk-id:NOT_BLANK' - 'urn:plmr:mfa:sk-id:NOT_NULL' type: string FieldError: type: object properties: code: $ref: '#/components/schemas/FieldErrorCode' message: type: string field: type: string ErrorResponse: type: object properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string requestId: type: string fieldErrors: type: array items: $ref: '#/components/schemas/FieldError' InitiateSigningResponse: type: object properties: verificationCode: type: string securitySchemes: cookieAuth: type: apiKey in: cookie name: auth-session parameters: challengeId: in: path name: challengeId required: true allowEmptyValue: false example: 2751d7d9-df79-4412-b4c4-28aaa7075548 schema: type: string minLength: 36 maxLength: 36 nullable: false description: | The ID of the challenge.