From 369ffe6033cf89303d952db73a0897d895fe9fd8 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 13 Oct 2026 19:25:59 +0000 Subject: [PATCH] chore: update v3 OpenAPI specs to v3.1004.0 --- CHANGELOG.md | 13 ++ specs/v3/openapi.yaml | 204 +++++++++++++++++- .../v3/v3-biometric-authentication-entry.yaml | 30 +++ specs/v3/v3-biometric-enrollment-entry.yaml | 30 +++ specs/v3/v3-biometric-kyc-entry.yaml | 30 +++ specs/v3/v3-document-verification-entry.yaml | 30 +++ ...-enhanced-document-verification-entry.yaml | 30 +++ ...residency-document-verification-entry.yaml | 38 +++- specs/v3/v3-smart-selfie-compare-entry.yaml | 30 +++ 9 files changed, 429 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 06159da..b050b37 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## [Unreleased] +## [v3.1004.0] - 2026-10-13 + +### Changed +- Updated `openapi` +- Updated `v3-biometric-authentication-entry` +- Updated `v3-biometric-enrollment-entry` +- Updated `v3-biometric-kyc-entry` +- Updated `v3-document-verification-entry` +- Updated `v3-enhanced-document-verification-entry` +- Updated `v3-residency-document-verification-entry` +- Updated `v3-smart-selfie-compare-entry` + + ## [v3.998.0] - 2026-10-12 ### Changed diff --git a/specs/v3/openapi.yaml b/specs/v3/openapi.yaml index 3836fd5..e3fdfb1 100644 --- a/specs/v3/openapi.yaml +++ b/specs/v3/openapi.yaml @@ -631,6 +631,16 @@ paths: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' + '422': + description: >- + Unprocessable Content — the encrypted SDK package could not be decrypted or parsed. Returned when `encrypted_package` is supplied and `package_nonce` or `package_tag` is missing or the wrong length, the SmileID-Source-SDK or SmileID-Source-SDK-Version header is missing or unrecognised, or decryption or JSON parsing fails. + content: + application/json: + schema: + $ref: '#/components/schemas/ApiErrorResponse' + example: + status: Unprocessable Content + message: Invalid payload. '429': description: Too Many Requests — rate limit exceeded. content: @@ -769,6 +779,16 @@ paths: example: status: Unsupported Media Type message: Unsupported Media Type. Required Content-Type is multipart/form-data + '422': + description: >- + Unprocessable Content — the encrypted SDK package could not be decrypted or parsed. Returned when `encrypted_package` is supplied and `package_nonce` or `package_tag` is missing or the wrong length, the SmileID-Source-SDK or SmileID-Source-SDK-Version header is missing or unrecognised, or decryption or JSON parsing fails. + content: + application/json: + schema: + $ref: '#/components/schemas/ApiErrorResponse' + example: + status: Unprocessable Content + message: Invalid payload. '429': description: Too Many Requests — rate limit exceeded. content: @@ -928,6 +948,16 @@ paths: example: status: Unsupported Media Type message: Unsupported Media Type. Required Content-Type is multipart/form-data + '422': + description: >- + Unprocessable Content — the encrypted SDK package could not be decrypted or parsed. Returned when `encrypted_package` is supplied and `package_nonce` or `package_tag` is missing or the wrong length, the SmileID-Source-SDK or SmileID-Source-SDK-Version header is missing or unrecognised, or decryption or JSON parsing fails. + content: + application/json: + schema: + $ref: '#/components/schemas/ApiErrorResponse' + example: + status: Unprocessable Content + message: Invalid payload. '429': description: Too Many Requests — rate limit exceeded for this ID number. content: @@ -1091,6 +1121,16 @@ paths: example: status: Unsupported Media Type message: Unsupported Media Type. Required Content-Type is multipart/form-data + '422': + description: >- + Unprocessable Content — the encrypted SDK package could not be decrypted or parsed. Returned when `encrypted_package` is supplied and `package_nonce` or `package_tag` is missing or the wrong length, the SmileID-Source-SDK or SmileID-Source-SDK-Version header is missing or unrecognised, or decryption or JSON parsing fails. + content: + application/json: + schema: + $ref: '#/components/schemas/ApiErrorResponse' + example: + status: Unprocessable Content + message: Invalid payload. '429': description: Too Many Requests — rate limit exceeded. content: @@ -1264,6 +1304,16 @@ paths: example: status: Unsupported Media Type message: Unsupported Media Type. Required Content-Type is multipart/form-data + '422': + description: >- + Unprocessable Content — the encrypted SDK package could not be decrypted or parsed. Returned when `encrypted_package` is supplied and `package_nonce` or `package_tag` is missing or the wrong length, the SmileID-Source-SDK or SmileID-Source-SDK-Version header is missing or unrecognised, or decryption or JSON parsing fails. + content: + application/json: + schema: + $ref: '#/components/schemas/ApiErrorResponse' + example: + status: Unprocessable Content + message: Invalid payload. '429': description: Too Many Requests — rate limit exceeded. content: @@ -2674,14 +2724,16 @@ paths: - name: SmileID-Source-SDK in: header required: false - description: Source SDK identifier. + description: >- + Source SDK identifier. Required when `encrypted_package` is supplied, together with SmileID-Source-SDK-Version, to select the decryption key. schema: type: string example: android - name: SmileID-Source-SDK-Version in: header required: false - description: Source SDK version. + description: >- + Source SDK version. Required when `encrypted_package` is supplied, together with SmileID-Source-SDK, to select the decryption key. schema: type: string example: 10.4.2 @@ -2690,7 +2742,7 @@ paths: required: false x-smile-sdk-exclude: true description: >- - ISO 8601 timestamp used as the salt when computing SmileID-Request-Signature. Required when your Smile ID account is configured to use SDK/partner secret HMAC authentication. + ISO 8601 timestamp used as the salt when computing SmileID-Request-Signature. Required when your Smile ID account is configured to use SDK/partner secret HMAC authentication. May be supplied inside `encrypted_package` instead of as a plain header. schema: type: string format: date-time @@ -2898,6 +2950,16 @@ paths: example: status: Unsupported Media Type message: Unsupported Media Type. Required Content-Type is multipart/form-data + '422': + description: >- + Unprocessable Content — the encrypted SDK package could not be decrypted or parsed. Returned when `encrypted_package` is supplied and `package_nonce` or `package_tag` is missing or the wrong length, the SmileID-Source-SDK or SmileID-Source-SDK-Version header is missing or unrecognised, or decryption or JSON parsing fails. + content: + application/json: + schema: + $ref: '#/components/schemas/ApiErrorResponse' + example: + status: Unprocessable Content + message: Invalid payload. '429': description: Too Many Requests — rate limit exceeded. content: @@ -3269,6 +3331,16 @@ paths: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' + '422': + description: >- + Unprocessable Content — the encrypted SDK package could not be decrypted or parsed. Returned when `encrypted_package` is supplied and `package_nonce` or `package_tag` is missing or the wrong length, the SmileID-Source-SDK or SmileID-Source-SDK-Version header is missing or unrecognised, or decryption or JSON parsing fails. + content: + application/json: + schema: + $ref: '#/components/schemas/ApiErrorResponse' + example: + status: Unprocessable Content + message: Invalid payload. '429': description: Too Many Requests — rate limit exceeded. content: @@ -4671,6 +4743,24 @@ components: type: object additionalProperties: type: string + encrypted_package: + type: string + pattern: ^[0-9a-fA-F]+$ + description: >- + Encrypted package produced by a Smile ID SDK. Forward it unchanged. When present, `package_nonce` and `package_tag` and the SmileID-Source-SDK and SmileID-Source-SDK-Version headers are required. + example: 9f3c1a7e52b08d46e1f27a9c3b5d80e4a6c2f19b7d3e05a8c4 + package_nonce: + type: string + pattern: ^[0-9a-fA-F]{24}$ + description: >- + Nonce for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: 0a1b2c3d4e5f60718293a4b5 + package_tag: + type: string + pattern: ^[0-9a-fA-F]{32}$ + description: >- + Tag for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: 00112233445566778899aabbccddeeff metadata: type: array items: @@ -4776,6 +4866,24 @@ components: description: Arbitrary key-value metadata for partner reference. example: order_id: ORD-12345 + encrypted_package: + type: string + pattern: ^[0-9a-fA-F]+$ + description: >- + Encrypted package produced by a Smile ID SDK. Forward it unchanged. When present, `package_nonce` and `package_tag` and the SmileID-Source-SDK and SmileID-Source-SDK-Version headers are required. + example: 9f3c1a7e52b08d46e1f27a9c3b5d80e4a6c2f19b7d3e05a8c4 + package_nonce: + type: string + pattern: ^[0-9a-fA-F]{24}$ + description: >- + Nonce for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: 0a1b2c3d4e5f60718293a4b5 + package_tag: + type: string + pattern: ^[0-9a-fA-F]{32}$ + description: >- + Tag for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: 00112233445566778899aabbccddeeff metadata: type: array description: Additional metadata entries (e.g., SDK telemetry, device info). @@ -4897,6 +5005,24 @@ components: description: Arbitrary key-value metadata for partner reference. example: order_id: ORD-12345 + encrypted_package: + type: string + pattern: ^[0-9a-fA-F]+$ + description: >- + Encrypted package produced by a Smile ID SDK. Forward it unchanged. When present, `package_nonce` and `package_tag` and the SmileID-Source-SDK and SmileID-Source-SDK-Version headers are required. + example: 9f3c1a7e52b08d46e1f27a9c3b5d80e4a6c2f19b7d3e05a8c4 + package_nonce: + type: string + pattern: ^[0-9a-fA-F]{24}$ + description: >- + Nonce for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: 0a1b2c3d4e5f60718293a4b5 + package_tag: + type: string + pattern: ^[0-9a-fA-F]{32}$ + description: >- + Tag for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: 00112233445566778899aabbccddeeff metadata: type: array description: Additional metadata entries (e.g., SDK telemetry, device info). @@ -5016,6 +5142,24 @@ components: description: Arbitrary key-value metadata for partner reference. example: order_id: ORD-12345 + encrypted_package: + type: string + pattern: ^[0-9a-fA-F]+$ + description: >- + Encrypted package produced by a Smile ID SDK. Forward it unchanged. When present, `package_nonce` and `package_tag` and the SmileID-Source-SDK and SmileID-Source-SDK-Version headers are required. + example: 9f3c1a7e52b08d46e1f27a9c3b5d80e4a6c2f19b7d3e05a8c4 + package_nonce: + type: string + pattern: ^[0-9a-fA-F]{24}$ + description: >- + Nonce for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: 0a1b2c3d4e5f60718293a4b5 + package_tag: + type: string + pattern: ^[0-9a-fA-F]{32}$ + description: >- + Tag for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: 00112233445566778899aabbccddeeff metadata: type: array description: Additional metadata entries (e.g., SDK telemetry, device info). @@ -5137,6 +5281,24 @@ components: description: Arbitrary key-value metadata for partner reference. example: order_id: ORD-12345 + encrypted_package: + type: string + pattern: ^[0-9a-fA-F]+$ + description: >- + Encrypted package produced by a Smile ID SDK. Forward it unchanged. When present, `package_nonce` and `package_tag` and the SmileID-Source-SDK and SmileID-Source-SDK-Version headers are required. + example: 9f3c1a7e52b08d46e1f27a9c3b5d80e4a6c2f19b7d3e05a8c4 + package_nonce: + type: string + pattern: ^[0-9a-fA-F]{24}$ + description: >- + Nonce for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: 0a1b2c3d4e5f60718293a4b5 + package_tag: + type: string + pattern: ^[0-9a-fA-F]{32}$ + description: >- + Tag for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: 00112233445566778899aabbccddeeff metadata: type: array description: Additional metadata entries (e.g., SDK telemetry, device info). @@ -5833,6 +5995,24 @@ components: description: Arbitrary key-value metadata for partner reference. example: order_id: ORD-12345 + encrypted_package: + type: string + pattern: ^[0-9a-fA-F]+$ + description: >- + Encrypted package produced by a Smile ID SDK. Forward it unchanged. When present, `package_nonce` and `package_tag` and the SmileID-Source-SDK and SmileID-Source-SDK-Version headers are required. + example: 9f3c1a7e52b08d46e1f27a9c3b5d80e4a6c2f19b7d3e05a8c4 + package_nonce: + type: string + pattern: ^[0-9a-fA-F]{24}$ + description: >- + Nonce for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: 0a1b2c3d4e5f60718293a4b5 + package_tag: + type: string + pattern: ^[0-9a-fA-F]{32}$ + description: >- + Tag for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: 00112233445566778899aabbccddeeff metadata: type: array description: Additional metadata entries (e.g., SDK telemetry, device info). @@ -6207,6 +6387,24 @@ components: type: object additionalProperties: type: string + encrypted_package: + type: string + pattern: ^[0-9a-fA-F]+$ + description: >- + Encrypted package produced by a Smile ID SDK. Forward it unchanged. When present, `package_nonce` and `package_tag` and the SmileID-Source-SDK and SmileID-Source-SDK-Version headers are required. + example: 9f3c1a7e52b08d46e1f27a9c3b5d80e4a6c2f19b7d3e05a8c4 + package_nonce: + type: string + pattern: ^[0-9a-fA-F]{24}$ + description: >- + Nonce for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: 0a1b2c3d4e5f60718293a4b5 + package_tag: + type: string + pattern: ^[0-9a-fA-F]{32}$ + description: >- + Tag for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: 00112233445566778899aabbccddeeff metadata: type: array items: diff --git a/specs/v3/v3-biometric-authentication-entry.yaml b/specs/v3/v3-biometric-authentication-entry.yaml index d937a15..3d40ed1 100644 --- a/specs/v3/v3-biometric-authentication-entry.yaml +++ b/specs/v3/v3-biometric-authentication-entry.yaml @@ -17,6 +17,8 @@ info: Authentication: token-based (token header from /v3/token). At least one of `email` or `phone_number` is required. The `user_id` field is required and must match an existing enrolled user. + + Encrypted SDK package: when a request is captured by a Smile ID SDK and forwarded by the partner's backend, the SDK can encrypt the request fields and headers into `encrypted_package` (with `package_nonce` and `package_tag`). The partner forwards these three form fields unchanged, alongside the image files and the SmileID-Source-SDK and SmileID-Source-SDK-Version headers. Smile ID decrypts the package before validation, so required fields may be supplied inside the package instead of as plain form fields. A package that cannot be decrypted or parsed is rejected with HTTP 422. tags: - name: Biometric Authentication paths: @@ -103,6 +105,16 @@ paths: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' + '422': + description: >- + Unprocessable Content — the encrypted SDK package could not be decrypted or parsed. Returned when `encrypted_package` is supplied and `package_nonce` or `package_tag` is missing or the wrong length, the SmileID-Source-SDK or SmileID-Source-SDK-Version header is missing or unrecognised, or decryption or JSON parsing fails. + content: + application/json: + schema: + $ref: '#/components/schemas/ApiErrorResponse' + example: + status: Unprocessable Content + message: Invalid payload. '429': description: Too Many Requests — rate limit exceeded. content: @@ -208,6 +220,24 @@ components: type: object additionalProperties: type: string + encrypted_package: + type: string + pattern: '^[0-9a-fA-F]+$' + description: >- + Encrypted package produced by a Smile ID SDK. Forward it unchanged. When present, `package_nonce` and `package_tag` and the SmileID-Source-SDK and SmileID-Source-SDK-Version headers are required. + example: '9f3c1a7e52b08d46e1f27a9c3b5d80e4a6c2f19b7d3e05a8c4' + package_nonce: + type: string + pattern: '^[0-9a-fA-F]{24}$' + description: >- + Nonce for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: '0a1b2c3d4e5f60718293a4b5' + package_tag: + type: string + pattern: '^[0-9a-fA-F]{32}$' + description: >- + Tag for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: '00112233445566778899aabbccddeeff' metadata: type: array items: diff --git a/specs/v3/v3-biometric-enrollment-entry.yaml b/specs/v3/v3-biometric-enrollment-entry.yaml index 391cb8a..4560345 100644 --- a/specs/v3/v3-biometric-enrollment-entry.yaml +++ b/specs/v3/v3-biometric-enrollment-entry.yaml @@ -19,6 +19,8 @@ info: At least one of `email` or `phone_number` is required. Token Payload: Identity fields (given_names, last_name, email, phone_number, callback_url) and the ISO 27560 consent fields can be bound to the authentication token via the token payload feature at /v3/token (PII fields are held as opaque references, never raw values). When present in the token, these fields are injected automatically and override any values in the request body. Fields provided via the token do not need to be repeated in the request body; GET /v3/services/config lists them as token_provided_fields. + + Encrypted SDK package: when a request is captured by a Smile ID SDK and forwarded by the partner's backend, the SDK can encrypt the request fields and headers into `encrypted_package` (with `package_nonce` and `package_tag`). The partner forwards these three form fields unchanged, alongside the image files and the SmileID-Source-SDK and SmileID-Source-SDK-Version headers. Smile ID decrypts the package before validation, so required fields may be supplied inside the package instead of as plain form fields. A package that cannot be decrypted or parsed is rejected with HTTP 422. tags: - name: Biometric Enrollment paths: @@ -147,6 +149,16 @@ paths: example: status: Content Too Large message: selfie_image is too large. + '422': + description: >- + Unprocessable Content — the encrypted SDK package could not be decrypted or parsed. Returned when `encrypted_package` is supplied and `package_nonce` or `package_tag` is missing or the wrong length, the SmileID-Source-SDK or SmileID-Source-SDK-Version header is missing or unrecognised, or decryption or JSON parsing fails. + content: + application/json: + schema: + $ref: '#/components/schemas/ApiErrorResponse' + example: + status: Unprocessable Content + message: Invalid payload. '429': description: Too Many Requests — rate limit exceeded. content: @@ -263,6 +275,24 @@ components: description: Arbitrary key-value metadata for partner reference. example: order_id: 'ORD-12345' + encrypted_package: + type: string + pattern: '^[0-9a-fA-F]+$' + description: >- + Encrypted package produced by a Smile ID SDK. Forward it unchanged. When present, `package_nonce` and `package_tag` and the SmileID-Source-SDK and SmileID-Source-SDK-Version headers are required. + example: '9f3c1a7e52b08d46e1f27a9c3b5d80e4a6c2f19b7d3e05a8c4' + package_nonce: + type: string + pattern: '^[0-9a-fA-F]{24}$' + description: >- + Nonce for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: '0a1b2c3d4e5f60718293a4b5' + package_tag: + type: string + pattern: '^[0-9a-fA-F]{32}$' + description: >- + Tag for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: '00112233445566778899aabbccddeeff' metadata: type: array description: Additional metadata entries (e.g., SDK telemetry, device info). diff --git a/specs/v3/v3-biometric-kyc-entry.yaml b/specs/v3/v3-biometric-kyc-entry.yaml index 15e0f7a..c5db5bf 100644 --- a/specs/v3/v3-biometric-kyc-entry.yaml +++ b/specs/v3/v3-biometric-kyc-entry.yaml @@ -19,6 +19,8 @@ info: At least one of `email` or `phone_number` is required. Token Payload: Identity fields (country, id_type, id_number, given_names, last_name, email, phone_number, callback_url) and the ISO 27560 consent fields can be bound to the authentication token via the token payload feature at /v3/token (PII fields are held as opaque references, never raw values). When present in the token, these fields are injected automatically and override any values in the request body. Fields provided via the token do not need to be repeated in the request body; GET /v3/services/config lists them as token_provided_fields. + + Encrypted SDK package: when a request is captured by a Smile ID SDK and forwarded by the partner's backend, the SDK can encrypt the request fields and headers into `encrypted_package` (with `package_nonce` and `package_tag`). The partner forwards these three form fields unchanged, alongside the image files and the SmileID-Source-SDK and SmileID-Source-SDK-Version headers. Smile ID decrypts the package before validation, so required fields may be supplied inside the package instead of as plain form fields. A package that cannot be decrypted or parsed is rejected with HTTP 422. tags: - name: Biometric KYC paths: @@ -162,6 +164,16 @@ paths: example: status: Unsupported Media Type message: Unsupported Media Type. Required Content-Type is multipart/form-data + '422': + description: >- + Unprocessable Content — the encrypted SDK package could not be decrypted or parsed. Returned when `encrypted_package` is supplied and `package_nonce` or `package_tag` is missing or the wrong length, the SmileID-Source-SDK or SmileID-Source-SDK-Version header is missing or unrecognised, or decryption or JSON parsing fails. + content: + application/json: + schema: + $ref: '#/components/schemas/ApiErrorResponse' + example: + status: Unprocessable Content + message: Invalid payload. '429': description: Too Many Requests — rate limit exceeded for this ID number. content: @@ -293,6 +305,24 @@ components: description: Arbitrary key-value metadata for partner reference. example: order_id: 'ORD-12345' + encrypted_package: + type: string + pattern: '^[0-9a-fA-F]+$' + description: >- + Encrypted package produced by a Smile ID SDK. Forward it unchanged. When present, `package_nonce` and `package_tag` and the SmileID-Source-SDK and SmileID-Source-SDK-Version headers are required. + example: '9f3c1a7e52b08d46e1f27a9c3b5d80e4a6c2f19b7d3e05a8c4' + package_nonce: + type: string + pattern: '^[0-9a-fA-F]{24}$' + description: >- + Nonce for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: '0a1b2c3d4e5f60718293a4b5' + package_tag: + type: string + pattern: '^[0-9a-fA-F]{32}$' + description: >- + Tag for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: '00112233445566778899aabbccddeeff' metadata: type: array description: Additional metadata entries (e.g., SDK telemetry, device info). diff --git a/specs/v3/v3-document-verification-entry.yaml b/specs/v3/v3-document-verification-entry.yaml index 3781ed3..c218418 100644 --- a/specs/v3/v3-document-verification-entry.yaml +++ b/specs/v3/v3-document-verification-entry.yaml @@ -19,6 +19,8 @@ info: At least one of `email` or `phone_number` is required. Token Payload: Identity fields (country, id_type, given_names, last_name, email, phone_number, callback_url) and the ISO 27560 consent fields can be bound to the authentication token via the token payload feature at /v3/token (PII fields are held as opaque references, never raw values). When present in the token, these fields are injected automatically and override any values in the request body. Fields provided via the token do not need to be repeated in the request body; GET /v3/services/config lists them as token_provided_fields. + + Encrypted SDK package: when a request is captured by a Smile ID SDK and forwarded by the partner's backend, the SDK can encrypt the request fields and headers into `encrypted_package` (with `package_nonce` and `package_tag`). The partner forwards these three form fields unchanged, alongside the image files and the SmileID-Source-SDK and SmileID-Source-SDK-Version headers. Smile ID decrypts the package before validation, so required fields may be supplied inside the package instead of as plain form fields. A package that cannot be decrypted or parsed is rejected with HTTP 422. tags: - name: Document Verification paths: @@ -166,6 +168,16 @@ paths: example: status: Unsupported Media Type message: Unsupported Media Type. Required Content-Type is multipart/form-data + '422': + description: >- + Unprocessable Content — the encrypted SDK package could not be decrypted or parsed. Returned when `encrypted_package` is supplied and `package_nonce` or `package_tag` is missing or the wrong length, the SmileID-Source-SDK or SmileID-Source-SDK-Version header is missing or unrecognised, or decryption or JSON parsing fails. + content: + application/json: + schema: + $ref: '#/components/schemas/ApiErrorResponse' + example: + status: Unprocessable Content + message: Invalid payload. '429': description: Too Many Requests — rate limit exceeded. content: @@ -296,6 +308,24 @@ components: description: Arbitrary key-value metadata for partner reference. example: order_id: 'ORD-12345' + encrypted_package: + type: string + pattern: '^[0-9a-fA-F]+$' + description: >- + Encrypted package produced by a Smile ID SDK. Forward it unchanged. When present, `package_nonce` and `package_tag` and the SmileID-Source-SDK and SmileID-Source-SDK-Version headers are required. + example: '9f3c1a7e52b08d46e1f27a9c3b5d80e4a6c2f19b7d3e05a8c4' + package_nonce: + type: string + pattern: '^[0-9a-fA-F]{24}$' + description: >- + Nonce for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: '0a1b2c3d4e5f60718293a4b5' + package_tag: + type: string + pattern: '^[0-9a-fA-F]{32}$' + description: >- + Tag for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: '00112233445566778899aabbccddeeff' metadata: type: array description: Additional metadata entries (e.g., SDK telemetry, device info). diff --git a/specs/v3/v3-enhanced-document-verification-entry.yaml b/specs/v3/v3-enhanced-document-verification-entry.yaml index 499293c..8f7e03e 100644 --- a/specs/v3/v3-enhanced-document-verification-entry.yaml +++ b/specs/v3/v3-enhanced-document-verification-entry.yaml @@ -19,6 +19,8 @@ info: At least one of `email` or `phone_number` is required. Token Payload: Identity fields (country, id_type, given_names, last_name, email, phone_number, callback_url) and the ISO 27560 consent fields can be bound to the authentication token via the token payload feature at /v3/token (PII fields are held as opaque references, never raw values). When present in the token, these fields are injected automatically and override any values in the request body. Fields provided via the token do not need to be repeated in the request body; GET /v3/services/config lists them as token_provided_fields. + + Encrypted SDK package: when a request is captured by a Smile ID SDK and forwarded by the partner's backend, the SDK can encrypt the request fields and headers into `encrypted_package` (with `package_nonce` and `package_tag`). The partner forwards these three form fields unchanged, alongside the image files and the SmileID-Source-SDK and SmileID-Source-SDK-Version headers. Smile ID decrypts the package before validation, so required fields may be supplied inside the package instead of as plain form fields. A package that cannot be decrypted or parsed is rejected with HTTP 422. tags: - name: Enhanced Document Verification paths: @@ -176,6 +178,16 @@ paths: example: status: Unsupported Media Type message: Unsupported Media Type. Required Content-Type is multipart/form-data + '422': + description: >- + Unprocessable Content — the encrypted SDK package could not be decrypted or parsed. Returned when `encrypted_package` is supplied and `package_nonce` or `package_tag` is missing or the wrong length, the SmileID-Source-SDK or SmileID-Source-SDK-Version header is missing or unrecognised, or decryption or JSON parsing fails. + content: + application/json: + schema: + $ref: '#/components/schemas/ApiErrorResponse' + example: + status: Unprocessable Content + message: Invalid payload. '429': description: Too Many Requests — rate limit exceeded. content: @@ -307,6 +319,24 @@ components: description: Arbitrary key-value metadata for partner reference. example: order_id: 'ORD-12345' + encrypted_package: + type: string + pattern: '^[0-9a-fA-F]+$' + description: >- + Encrypted package produced by a Smile ID SDK. Forward it unchanged. When present, `package_nonce` and `package_tag` and the SmileID-Source-SDK and SmileID-Source-SDK-Version headers are required. + example: '9f3c1a7e52b08d46e1f27a9c3b5d80e4a6c2f19b7d3e05a8c4' + package_nonce: + type: string + pattern: '^[0-9a-fA-F]{24}$' + description: >- + Nonce for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: '0a1b2c3d4e5f60718293a4b5' + package_tag: + type: string + pattern: '^[0-9a-fA-F]{32}$' + description: >- + Tag for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: '00112233445566778899aabbccddeeff' metadata: type: array description: Additional metadata entries (e.g., SDK telemetry, device info). diff --git a/specs/v3/v3-residency-document-verification-entry.yaml b/specs/v3/v3-residency-document-verification-entry.yaml index 263f739..c934f7b 100644 --- a/specs/v3/v3-residency-document-verification-entry.yaml +++ b/specs/v3/v3-residency-document-verification-entry.yaml @@ -23,6 +23,8 @@ info: At least one of `email` or `phone_number` is required. Token Payload: Identity fields (country, id_type, given_names, last_name, email, phone_number, callback_url) and the ISO 27560 consent fields can be bound to the authentication token via the token payload feature at /v3/token (PII fields are held as opaque references, never raw values). When present in the token, these fields are injected automatically and override any values in the request body. Fields provided via the token do not need to be repeated in the request body; GET /v3/services/config lists them as token_provided_fields. + + Encrypted SDK package: when a request is captured by a Smile ID SDK and forwarded by the partner's backend, the SDK can encrypt the request fields and headers into `encrypted_package` (with `package_nonce` and `package_tag`). The partner forwards these three form fields unchanged, alongside the image files and the SmileID-Source-SDK and SmileID-Source-SDK-Version headers. Smile ID decrypts the package before validation, so required fields may be supplied inside the package instead of as plain form fields. A package that cannot be decrypted or parsed is rejected with HTTP 422. tags: - name: Residency Document Verification paths: @@ -48,14 +50,16 @@ paths: - name: SmileID-Source-SDK in: header required: false - description: Source SDK identifier. + description: >- + Source SDK identifier. Required when `encrypted_package` is supplied, together with SmileID-Source-SDK-Version, to select the decryption key. schema: type: string example: 'android' - name: SmileID-Source-SDK-Version in: header required: false - description: Source SDK version. + description: >- + Source SDK version. Required when `encrypted_package` is supplied, together with SmileID-Source-SDK, to select the decryption key. schema: type: string example: '10.4.2' @@ -64,7 +68,7 @@ paths: required: false x-smile-sdk-exclude: true description: >- - ISO 8601 timestamp used as the salt when computing SmileID-Request-Signature. Required when your Smile ID account is configured to use SDK/partner secret HMAC authentication. + ISO 8601 timestamp used as the salt when computing SmileID-Request-Signature. Required when your Smile ID account is configured to use SDK/partner secret HMAC authentication. May be supplied inside `encrypted_package` instead of as a plain header. schema: type: string format: date-time @@ -271,6 +275,16 @@ paths: example: status: Unsupported Media Type message: Unsupported Media Type. Required Content-Type is multipart/form-data + '422': + description: >- + Unprocessable Content — the encrypted SDK package could not be decrypted or parsed. Returned when `encrypted_package` is supplied and `package_nonce` or `package_tag` is missing or the wrong length, the SmileID-Source-SDK or SmileID-Source-SDK-Version header is missing or unrecognised, or decryption or JSON parsing fails. + content: + application/json: + schema: + $ref: '#/components/schemas/ApiErrorResponse' + example: + status: Unprocessable Content + message: Invalid payload. '429': description: Too Many Requests — rate limit exceeded. content: @@ -405,6 +419,24 @@ components: description: Arbitrary key-value metadata for partner reference. example: order_id: 'ORD-12345' + encrypted_package: + type: string + pattern: '^[0-9a-fA-F]+$' + description: >- + Encrypted package produced by a Smile ID SDK. Forward it unchanged. When present, `package_nonce` and `package_tag` and the SmileID-Source-SDK and SmileID-Source-SDK-Version headers are required. + example: '9f3c1a7e52b08d46e1f27a9c3b5d80e4a6c2f19b7d3e05a8c4' + package_nonce: + type: string + pattern: '^[0-9a-fA-F]{24}$' + description: >- + Nonce for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: '0a1b2c3d4e5f60718293a4b5' + package_tag: + type: string + pattern: '^[0-9a-fA-F]{32}$' + description: >- + Tag for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: '00112233445566778899aabbccddeeff' metadata: type: array description: Additional metadata entries (e.g., SDK telemetry, device info). diff --git a/specs/v3/v3-smart-selfie-compare-entry.yaml b/specs/v3/v3-smart-selfie-compare-entry.yaml index 5143d4b..24ffb65 100644 --- a/specs/v3/v3-smart-selfie-compare-entry.yaml +++ b/specs/v3/v3-smart-selfie-compare-entry.yaml @@ -17,6 +17,8 @@ info: Authentication: token-based (token header from /v3/token). At least one of `email` or `phone_number` is required. + + Encrypted SDK package: when a request is captured by a Smile ID SDK and forwarded by the partner's backend, the SDK can encrypt the request fields and headers into `encrypted_package` (with `package_nonce` and `package_tag`). The partner forwards these three form fields unchanged, alongside the image files and the SmileID-Source-SDK and SmileID-Source-SDK-Version headers. Smile ID decrypts the package before validation, so required fields may be supplied inside the package instead of as plain form fields. A package that cannot be decrypted or parsed is rejected with HTTP 422. tags: - name: Smart Selfie Compare paths: @@ -115,6 +117,16 @@ paths: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' + '422': + description: >- + Unprocessable Content — the encrypted SDK package could not be decrypted or parsed. Returned when `encrypted_package` is supplied and `package_nonce` or `package_tag` is missing or the wrong length, the SmileID-Source-SDK or SmileID-Source-SDK-Version header is missing or unrecognised, or decryption or JSON parsing fails. + content: + application/json: + schema: + $ref: '#/components/schemas/ApiErrorResponse' + example: + status: Unprocessable Content + message: Invalid payload. '429': description: Too Many Requests — rate limit exceeded. content: @@ -223,6 +235,24 @@ components: type: object additionalProperties: type: string + encrypted_package: + type: string + pattern: '^[0-9a-fA-F]+$' + description: >- + Encrypted package produced by a Smile ID SDK. Forward it unchanged. When present, `package_nonce` and `package_tag` and the SmileID-Source-SDK and SmileID-Source-SDK-Version headers are required. + example: '9f3c1a7e52b08d46e1f27a9c3b5d80e4a6c2f19b7d3e05a8c4' + package_nonce: + type: string + pattern: '^[0-9a-fA-F]{24}$' + description: >- + Nonce for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: '0a1b2c3d4e5f60718293a4b5' + package_tag: + type: string + pattern: '^[0-9a-fA-F]{32}$' + description: >- + Tag for `encrypted_package`, produced by a Smile ID SDK. Forward it unchanged. Required when `encrypted_package` is supplied. + example: '00112233445566778899aabbccddeeff' metadata: type: array items: