From 051759417f8d7d9041c95158765c20276b11fdb6 Mon Sep 17 00:00:00 2001 From: Fernando Prado Date: Thu, 19 Jun 2025 17:21:34 +0200 Subject: [PATCH 01/12] update version and remove AUTHENTICATION_REQUIRED error --- code/API_definitions/number-verification.yaml | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) diff --git a/code/API_definitions/number-verification.yaml b/code/API_definitions/number-verification.yaml index 6e3387b..156ea5b 100644 --- a/code/API_definitions/number-verification.yaml +++ b/code/API_definitions/number-verification.yaml @@ -72,7 +72,7 @@ info: In the case of the Number Verification API scenario and according to the API definition, 3-legged access tokens must be used by API clients to invoke this API with dedicated scope. The API client must authenticate on behalf of a specific user to use this service. This must be done via mobile network authentication. - version: wip + version: 2.1.0-rc.1 x-camara-commonalities: 0.5 license: name: Apache 2.0 @@ -81,7 +81,7 @@ externalDocs: description: Project documentation at CAMARA url: https://github.com/camaraproject/NumberVerification servers: - - url: '{apiRoot}/number-verification/vwip' + - url: '{apiRoot}/number-verification/v2rc1' variables: apiRoot: default: http://localhost:9091 @@ -279,20 +279,13 @@ components: code: enum: - UNAUTHENTICATED - - AUTHENTICATION_REQUIRED examples: GENERIC_401_UNAUTHENTICATED: - description: Request cannot be authenticated + description: Request cannot be authenticated and a new authentication is required value: status: 401 code: UNAUTHENTICATED - message: Request not authenticated due to missing, invalid, or expired credentials. - GENERIC_401_AUTHENTICATION_REQUIRED: - description: New authentication is needed, authentication is no longer valid - value: - status: 401 - code: AUTHENTICATION_REQUIRED - message: New authentication is required. + message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required. PhoneNumberVerificationPermissionDenied403: description: | Client does not have sufficient permission. From 7e7cefad38f378e4f4614e6302c5d5884aefc594 Mon Sep 17 00:00:00 2001 From: Fernando Prado Date: Mon, 23 Jun 2025 16:45:24 +0200 Subject: [PATCH 02/12] update changelog --- CHANGELOG.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3ffefd5..1d16315 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ ## Table of contents +- **[r3.1](#r24) Fall25** - **[r2.4](#r24) Spring25** - ~~[r2.3](#r23)~~ - **[r2.2](#r22)** @@ -22,6 +23,41 @@ The below sections record the changes for each API version in each release as fo * for subsequent release-candidate(s), only the delta to the previous release-candidate * for a public release, the consolidated changes since the previous public release +# r3.1 + +This **public release** contains the definition and documentation of +* number-verification 2.1.0-rc.1 + +The API definition(s) are based on +* Commonalities v0.6.0-rc.1 +* Identity and Consent Management v0.4.0-rc.1 + +## number-verification 2.1.0-rc.1 + +**number-verification 2.1.0-rc.1 is the first pre-release for v2.0.0-rc.1 of the NumberVerification API.** + +- API definition **with inline documentation**: + - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r3.1/code/API_definitions/number-verification.yaml&nocors) + - [View it on Swagger Editor](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r3.1/code/API_definitions/number-verification.yaml) + - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/r3.1/code/API_definitions/number-verification.yaml) + +### Added + +- Add pattern validation for hashedPhoneNumber by @ravindrapalaskar17 in https://github.com/camaraproject/NumberVerification/pull/188 +- Documented Error Responses info.description section by @bigludo7 in https://github.com/camaraproject/NumberVerification/pull/199 + +### Changed + +- Update README.md - adding Number Insights as Sub Project by @hdamker in https://github.com/camaraproject/NumberVerification/pull/195 +- Update x-correlator format by @bigludo7 in https://github.com/camaraproject/NumberVerification/pull/200 +- Update test plan by @fernandopradocabrilo in https://github.com/camaraproject/NumberVerification/pull/204 + +## New Contributors +* @ravindrapalaskar17 made their first contribution in https://github.com/camaraproject/NumberVerification/pull/188 +* @hdamker-bot made their first contribution in https://github.com/camaraproject/NumberVerification/pull/196 + +**Full Changelog**: https://github.com/camaraproject/NumberVerification/compare/r2.4...r3.1 + # r2.4 ## Release Notes From 240872ea7fdfed7b3550c13b3bd3fe06f0204417 Mon Sep 17 00:00:00 2001 From: Fernando Prado Date: Mon, 23 Jun 2025 16:45:46 +0200 Subject: [PATCH 03/12] update api readiness checklist --- .../number-verification-API-Readiness-Checklist.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/documentation/API_documentation/number-verification-API-Readiness-Checklist.md b/documentation/API_documentation/number-verification-API-Readiness-Checklist.md index 2cbc18c..ec1915b 100644 --- a/documentation/API_documentation/number-verification-API-Readiness-Checklist.md +++ b/documentation/API_documentation/number-verification-API-Readiness-Checklist.md @@ -1,21 +1,22 @@ # API Readiness Checklist -Checklist for number-verification v2.0.0 in release r2.4 +Checklist for number-verification v2.1.0 in release r3.1 | Nr | API release assets | alpha | release-candidate | public-release
initial | public-release
stable | Status | Reference information | |----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|:----:| -| 1 | API definition | M | M | M | M | Y | [link](/code/API_definitions/number-verification.yaml) | -| 2 | Design guidelines from Commonalities applied | O | M | M | M | Y | [r2.3](https://github.com/camaraproject/Commonalities/releases/tag/r2.3) | -| 3 | Guidelines from ICM applied | O | M | M | M | Y | [r2.3](https://github.com/camaraproject/IdentityAndConsentManagement/releases/tag/r2.3) | +| 1 | API definition | M | M | M | M | Y | [link](/code/API_definitions/number-verification.yaml) | +| 2 | Design guidelines from Commonalities applied | O | M | M | M | Y | [r3.2](https://github.com/camaraproject/Commonalities/releases/tag/r3.2) | +| 3 | Guidelines from ICM applied | O | M | M | M | Y | [r3.2](https://github.com/camaraproject/IdentityAndConsentManagement/releases/tag/r3.2) | | 4 | API versioning convention applied | M | M | M | M | Y | | | 5 | API documentation | M | M | M | M | Y | Embedded documentation into API spec - [link](/code/API_definitions/number-verification.yaml) | | 6 | User stories | O | O | O | M | Y | [get](/documentation/API_documentation/NumberVerification_device_phone_number_User_Story.md) [verify](/documentation/API_documentation/NumberVerification_verify_User_Story.md) | -| 7 | Basic API test cases & documentation | O | M | M | M | Y | [get](code/Test_Definitions/number-verification-device-phone-number-share.feature) [verify](/code/Test_Definitions/number-verification-verify.feature) | -| 8 | Enhanced API test cases & documentation | O | O | O | M | Y | [get](code/Test_Definitions/number-verification-device-phone-number-share.feature) [verify](code/Test_Definitions/number-verification-verify.feature) | +| 7 | Basic API test cases & documentation | O | M | M | M | Y | [get](code/Test_Definitions/number-verification-phoneNumberShare.feature) [verify](/code/Test_Definitions/number-verification-phoneNumberVerify.feature) | +| 8 | Enhanced API test cases & documentation | O | O | O | M | Y | [get](code/Test_Definitions/number-verification-phoneNumberShare.feature) [verify](code/Test_Definitions/number-verification-phoneNumberVerify.feature) | | 9 | Test result statement | O | O | O | M | N | see [issue #166](https://github.com/camaraproject/NumberVerification/issues/166) | | 10 | API release numbering convention applied | M | M | M | M | Y | | | 11 | Change log updated | M | M | M | M | Y | [link](/CHANGELOG.md) | | 12 | Previous public-release was certified | O | O | O | M | Y | [link](https://www.open-gateway.com/operators-map) | +| 13 | API description (for marketing) | O | O | M | M | Y | [wiki link](https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/81134263/NumberVerification+API+description) | To fill the checklist: From c54efe764687e82e3f608f8e450f18809c52e4e0 Mon Sep 17 00:00:00 2001 From: Fernando Prado Date: Mon, 23 Jun 2025 17:10:21 +0200 Subject: [PATCH 04/12] update readme --- README.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 47bb24c..1ab7862 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,13 @@ Incubating API Repository to evolve and maintain the definitions and documentati * Note: Please be aware that the project will have frequent updates to the main branch. There are no compatibility guarantees associated with code in any branch, including main, until a new release is created. For example, changes may be reverted before a release is created. **For best results, use the latest available release**. -* The public release r2.4 with version 2.0.0 of the API number-verification is available [here](https://github.com/camaraproject/NumberVerification/tree/r2.4) +* **NEW**: The pre-release r3.1 with version 2.1.0-rc.1 of the API number-verification is available [here](https://github.com/camaraproject/NumberVerification/tree/r3.1) + - 2.1.0-rc.1 Number Verification definition **with inline documentation**: + - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/r3.1/code/API_definitions/number-verification.yaml) + - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r3.1/code/API_definitions/number-verification.yaml&nocors) + - [View it on Swagger Editor](https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r3.1/code/API_definitions/number-verification.yaml) + +* The latest public release r2.4 with version 2.0.0 of the API number-verification is available [here](https://github.com/camaraproject/NumberVerification/tree/r2.4) - 2.0.0 Number Verification definition **with inline documentation**: - OpenAPI [YAML spec file](https://github.com/camaraproject/NumberVerification/blob/r2.4/code/API_definitions/number-verification.yaml) - [View it on ReDoc](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/camaraproject/NumberVerification/r2.4/code/API_definitions/number-verification.yaml&nocors) From 270234a4e346a80059040248d260b6fd3f96a205 Mon Sep 17 00:00:00 2001 From: Fernando Prado Date: Mon, 23 Jun 2025 17:11:11 +0200 Subject: [PATCH 05/12] update x-camara-commonalitties --- code/API_definitions/number-verification.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/number-verification.yaml b/code/API_definitions/number-verification.yaml index 156ea5b..7fe1a72 100644 --- a/code/API_definitions/number-verification.yaml +++ b/code/API_definitions/number-verification.yaml @@ -73,7 +73,7 @@ info: In the case of the Number Verification API scenario and according to the API definition, 3-legged access tokens must be used by API clients to invoke this API with dedicated scope. The API client must authenticate on behalf of a specific user to use this service. This must be done via mobile network authentication. version: 2.1.0-rc.1 - x-camara-commonalities: 0.5 + x-camara-commonalities: 0.6 license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html From 17785976a0d60ccabe6c24642b29dd6a0ad1aaf0 Mon Sep 17 00:00:00 2001 From: Fernando Prado Cabrillo Date: Mon, 23 Jun 2025 18:25:32 +0200 Subject: [PATCH 06/12] fix version link in changelog.md table of contents --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1d16315..e0c241d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,7 +3,7 @@ ## Table of contents -- **[r3.1](#r24) Fall25** +- **[r3.1](#r31) Fall25** - **[r2.4](#r24) Spring25** - ~~[r2.3](#r23)~~ - **[r2.2](#r22)** From ab5f2a1480b107136580495ba21d0e6589b69c5b Mon Sep 17 00:00:00 2001 From: Fernando Prado Date: Wed, 2 Jul 2025 14:59:32 +0200 Subject: [PATCH 07/12] include jwt-bearer text and update changelog --- CHANGELOG.md | 6 +++++- code/API_definitions/number-verification.yaml | 5 ++++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e0c241d..b5ba003 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -45,6 +45,7 @@ The API definition(s) are based on - Add pattern validation for hashedPhoneNumber by @ravindrapalaskar17 in https://github.com/camaraproject/NumberVerification/pull/188 - Documented Error Responses info.description section by @bigludo7 in https://github.com/camaraproject/NumberVerification/pull/199 +- Include documentation to use with JWT-bearer auth flow by @fernandopradocabrillo in https://github.com/camaraproject/NumberVerification/pull/206 ### Changed @@ -52,9 +53,12 @@ The API definition(s) are based on - Update x-correlator format by @bigludo7 in https://github.com/camaraproject/NumberVerification/pull/200 - Update test plan by @fernandopradocabrilo in https://github.com/camaraproject/NumberVerification/pull/204 +### Removed + +- Remove AUTHENTICATION_REQUIRED error by @fernandopradocabrillo in https://github.com/camaraproject/NumberVerification/pull/206 + ## New Contributors * @ravindrapalaskar17 made their first contribution in https://github.com/camaraproject/NumberVerification/pull/188 -* @hdamker-bot made their first contribution in https://github.com/camaraproject/NumberVerification/pull/196 **Full Changelog**: https://github.com/camaraproject/NumberVerification/compare/r2.4...r3.1 diff --git a/code/API_definitions/number-verification.yaml b/code/API_definitions/number-verification.yaml index 7fe1a72..6d267f3 100644 --- a/code/API_definitions/number-verification.yaml +++ b/code/API_definitions/number-verification.yaml @@ -27,7 +27,10 @@ info: ## Authentication Request with a temporary token If the API Consumer has a TS.43 temporary token created on the mobile device then this API works over all connections e.g. WiFi taking advantage of the SIM-Based authentication. - The API Consumer sends the temporary token to their backend which sends a CIBA Authentication Request, as described in the current release [CAMARA APIs Access and User Consent Management](https://github.com/camaraproject/IdentityAndConsentManagement), with a parameter "login_hint=operatortoken:". + The API Consumer sends the temporary token to their backend which either: + - Sends a CIBA Authentication Request, as described in the current release [CAMARA APIs Access and User Consent Management](https://github.com/camaraproject/IdentityAndConsentManagement), with a parameter `login_hint=operatortoken:`. + - Or sends a JWT-Bearer token request as described in [CAMARA APIs Access and User Consent Management](https://github.com/camaraproject/IdentityAndConsentManagement), with the TS.43 token in the `sub` claim of the JWT assertion with the format `"operatortoken:"`. + How the API Consumers get a TS.43 temporary token and how this token is sent to their backend, is out-of-scope of the API definition. ## Authentication Request without a temporary token From 242875f3d3ac631efe708de92ab59300d1a474fe Mon Sep 17 00:00:00 2001 From: Fernando Prado Cabrillo Date: Thu, 3 Jul 2025 10:53:11 +0200 Subject: [PATCH 08/12] Update documentation/API_documentation/number-verification-API-Readiness-Checklist.md --- .../number-verification-API-Readiness-Checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API_documentation/number-verification-API-Readiness-Checklist.md b/documentation/API_documentation/number-verification-API-Readiness-Checklist.md index ec1915b..7d4cb4c 100644 --- a/documentation/API_documentation/number-verification-API-Readiness-Checklist.md +++ b/documentation/API_documentation/number-verification-API-Readiness-Checklist.md @@ -1,6 +1,6 @@ # API Readiness Checklist -Checklist for number-verification v2.1.0 in release r3.1 +Checklist for number-verification v2.1.0-rc.1 in release r3.1 | Nr | API release assets | alpha | release-candidate | public-release
initial | public-release
stable | Status | Reference information | |----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|:----:| From dc278e46156ff07753fc30537957b115ed20d2a6 Mon Sep 17 00:00:00 2001 From: Fernando Prado Date: Thu, 10 Jul 2025 12:20:08 +0200 Subject: [PATCH 09/12] remove trailing spaces --- code/API_definitions/number-verification.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/number-verification.yaml b/code/API_definitions/number-verification.yaml index 54a736f..b894a66 100644 --- a/code/API_definitions/number-verification.yaml +++ b/code/API_definitions/number-verification.yaml @@ -29,7 +29,7 @@ info: If the API Consumer has a TS.43 temporary token created on the mobile device then this API works over all connections e.g. WiFi taking advantage of the SIM-Based authentication. The API Consumer sends the temporary token to their backend which either: - Sends a CIBA Authentication Request, as described in the current release [CAMARA APIs Access and User Consent Management](https://github.com/camaraproject/IdentityAndConsentManagement), with a parameter `login_hint=operatortoken:`. - - Or sends a JWT-Bearer token request as described in [CAMARA APIs Access and User Consent Management](https://github.com/camaraproject/IdentityAndConsentManagement), with the TS.43 token in the `sub` claim of the JWT assertion with the format `"operatortoken:"`. + - Or sends a JWT-Bearer token request as described in [CAMARA APIs Access and User Consent Management](https://github.com/camaraproject/IdentityAndConsentManagement), with the TS.43 token in the `sub` claim of the JWT assertion with the format `"operatortoken:"`. How the API Consumers get a TS.43 temporary token and how this token is sent to their backend, is out-of-scope of the API definition. From 87b841cda77584d64ba8ffc56ba9a7e379c1f746 Mon Sep 17 00:00:00 2001 From: Fernando Prado Date: Thu, 17 Jul 2025 09:45:52 +0200 Subject: [PATCH 10/12] update version in test plan --- .../number-verification-phoneNumberShare.feature | 4 ++-- .../number-verification-phoneNumberVerify.feature | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/code/Test_Definitions/number-verification-phoneNumberShare.feature b/code/Test_Definitions/number-verification-phoneNumberShare.feature index 92bc21a..6e85f53 100644 --- a/code/Test_Definitions/number-verification-phoneNumberShare.feature +++ b/code/Test_Definitions/number-verification-phoneNumberShare.feature @@ -1,4 +1,4 @@ -Feature: CAMARA Number Verification API, vwip - Operation phoneNumberShare +Feature: CAMARA Number Verification API, v2.1.0-rc.1 - Operation phoneNumberShare # Input to be provided by the implementation to the tester # @@ -10,7 +10,7 @@ Feature: CAMARA Number Verification API, vwip - Operation phoneNumberShare Background: Common phoneNumberShare setup - Given the resource "/number-verification/vwip" as base url + Given the resource "/number-verification/v2rc1" as base url And the header "Content-Type" is set to "application/json" And the header "Authorization" is set to a valid access token And the header "x-correlator" complies with the schema at "#/components/schemas/XCorrelator" diff --git a/code/Test_Definitions/number-verification-phoneNumberVerify.feature b/code/Test_Definitions/number-verification-phoneNumberVerify.feature index aa80c47..3ab3d9a 100644 --- a/code/Test_Definitions/number-verification-phoneNumberVerify.feature +++ b/code/Test_Definitions/number-verification-phoneNumberVerify.feature @@ -1,4 +1,4 @@ -Feature: CAMARA Number Verification API, vwip - Operation phoneNumberVerify +Feature: CAMARA Number Verification API, v2.1.0-rc.1 - Operation phoneNumberVerify # Input to be provided by the implementation to the tester # @@ -11,7 +11,7 @@ Feature: CAMARA Number Verification API, vwip - Operation phoneNumberVerify Background: Common phoneNumberVerify setup - Given the resource "/number-verification/vwip" as base url + Given the resource "/number-verification/v2rc1" as base url And the header "Content-Type" is set to "application/json" And the header "Authorization" is set to a valid access token And the header "x-correlator" complies with the schema at "#/components/schemas/XCorrelator" From c5f99826918c0f7aa8ee4a7ff0fd2c448123e605 Mon Sep 17 00:00:00 2001 From: Fernando Prado Cabrillo Date: Thu, 17 Jul 2025 11:52:08 +0200 Subject: [PATCH 11/12] remove test statement Co-authored-by: Herbert Damker --- .../number-verification-API-Readiness-Checklist.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API_documentation/number-verification-API-Readiness-Checklist.md b/documentation/API_documentation/number-verification-API-Readiness-Checklist.md index 7d4cb4c..04934d5 100644 --- a/documentation/API_documentation/number-verification-API-Readiness-Checklist.md +++ b/documentation/API_documentation/number-verification-API-Readiness-Checklist.md @@ -12,7 +12,7 @@ Checklist for number-verification v2.1.0-rc.1 in release r3.1 | 6 | User stories | O | O | O | M | Y | [get](/documentation/API_documentation/NumberVerification_device_phone_number_User_Story.md) [verify](/documentation/API_documentation/NumberVerification_verify_User_Story.md) | | 7 | Basic API test cases & documentation | O | M | M | M | Y | [get](code/Test_Definitions/number-verification-phoneNumberShare.feature) [verify](/code/Test_Definitions/number-verification-phoneNumberVerify.feature) | | 8 | Enhanced API test cases & documentation | O | O | O | M | Y | [get](code/Test_Definitions/number-verification-phoneNumberShare.feature) [verify](code/Test_Definitions/number-verification-phoneNumberVerify.feature) | -| 9 | Test result statement | O | O | O | M | N | see [issue #166](https://github.com/camaraproject/NumberVerification/issues/166) | +| 9 | Test result statement | O | O | O | M | N | | | 10 | API release numbering convention applied | M | M | M | M | Y | | | 11 | Change log updated | M | M | M | M | Y | [link](/CHANGELOG.md) | | 12 | Previous public-release was certified | O | O | O | M | Y | [link](https://www.open-gateway.com/operators-map) | From c2b6864a814d5f835cf42d31dbc0dfbbb6f852f5 Mon Sep 17 00:00:00 2001 From: Fernando Prado Cabrillo Date: Thu, 17 Jul 2025 11:53:15 +0200 Subject: [PATCH 12/12] remove wg name change reference from changelog --- CHANGELOG.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b5ba003..4c65a23 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -49,7 +49,6 @@ The API definition(s) are based on ### Changed -- Update README.md - adding Number Insights as Sub Project by @hdamker in https://github.com/camaraproject/NumberVerification/pull/195 - Update x-correlator format by @bigludo7 in https://github.com/camaraproject/NumberVerification/pull/200 - Update test plan by @fernandopradocabrilo in https://github.com/camaraproject/NumberVerification/pull/204