From 2c40283dc1fd5c69808d11f09c6b0c1393e89396 Mon Sep 17 00:00:00 2001 From: ToshiWakayama-KDDI <53090722+ToshiWakayama-KDDI@users.noreply.github.com> Date: Fri, 2 Feb 2024 19:36:53 +0900 Subject: [PATCH 01/44] Initial contribution of Age_Verification.yaml --- code/API_definitions/age-vefification.yaml | 27 ++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 code/API_definitions/age-vefification.yaml diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml new file mode 100644 index 0000000..86a9070 --- /dev/null +++ b/code/API_definitions/age-vefification.yaml @@ -0,0 +1,27 @@ +openapi: 3.0.3 +info: + title: Age Verification + + termsOfService: http://swagger.io/terms/ + contact: + email: project-email@sample.com + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + + version: 0.1.0-wip + + +servers: + - url: '{apiRoot}/{basePath}' + variables: + apiRoot: + default: http://localhost:9091 + description: API root + basePath: + default: age-verificaiton/v0 + description: Base path for the Age Verification API + + + + From ed7003f747f6bc6b7c8e5a502ef231a514bf5324 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Fri, 2 Feb 2024 14:05:07 +0100 Subject: [PATCH 02/44] Update age-verification.yaml Update the design proposal for Age Verification API specifications --- code/API_definitions/age-vefification.yaml | 283 ++++++++++++++++++++- 1 file changed, 280 insertions(+), 3 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index 86a9070..2d23343 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -1,6 +1,6 @@ openapi: 3.0.3 info: - title: Age Verification + title: Know Your Customer Age Verification termsOfService: http://swagger.io/terms/ contact: @@ -19,9 +19,286 @@ servers: default: http://localhost:9091 description: API root basePath: - default: age-verificaiton/v0 - description: Base path for the Age Verification API + default: kyc-ageverification/v0 + description: Base path for the KYC-AgeVerification API +tags: + - name: AgeVerification + description: Operations to verify the age of a user. +paths: + /ageverification: + post: + tags: + - AgeVerification + summary: Verify if the age of a user is under the provided age value submitted in order to automatically denied access to gaming, alcohol, or other age-restricted sites. + operationId: KYC_AgeVerification + + security: + - openId: + - know-your-customer:AgeVerification + + + parameters: + - $ref: '#/components/parameters/x-correlator' + + requestBody: + required: true + content: + application/json: + + schema: + $ref: '#/components/schemas/KYC_RequestBody' + examples: + AgeVerificationRequestExample: + value: + phoneNumber: '+34629255833' + age: 18 + + responses: + '200': + description: OK + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + + content: + application/json: + + schema: + $ref: '#/components/schemas/KYC_ResponseBody' + examples: + KYC_200Example: + value: + phoneNumber: '+34629255833' + isVerified: true + + '400': + $ref: '#/components/responses/Generic400' + + '401': + $ref: '#/components/responses/Generic401' + + '403': + $ref: '#/components/responses/Generic403' + + '404': + $ref: '#/components/responses/Generic404' + + '500': + $ref: '#/components/responses/Generic500' + + '503': + $ref: '#/components/responses/Generic503' + + '504': + $ref: '#/components/responses/Generic504' + +components: + securitySchemes: + openId: + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration + + + headers: + x-correlator: + description: Correlation id for the different services + schema: + type: "string" + + parameters: + x-correlator: + name: x-correlator + in: header + description: Correlation id for the different services + schema: + type: "string" + + schemas: + KYC_RequestBody: + description: "Requested information to be compare with customer personal information" + type: "object" + + properties: + phoneNumber: + type: "string" + description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, optionally prefixed with '+'. + + age: + type: "integer" + description: age to be verified. + + + KYC_ResponseBody: + type: "object" + properties: + + phoneNumber: + type: "string" + description: A public identifier addressing a telephone subscription. + + isVerified: + type: "boolean" + default: True + description: Indicates if the age has been verified (True) or if it has not been possible (False). + + ErrorInfo: + type: "object" + required: + - status + - code + - message + properties: + status: + type: "integer" + description: HTTP response status code + code: + type: "string" + description: Code given to this error + message: + type: "string" + description: Detailed error description + + responses: + Generic400: + description: |- + Problem with the client request. + In addition to regular scenario of `INVALID_ARGUMENT`, another scenario may exist. + + - Indicated param combination is invalid (`"code": "KNOW_YOUR_CUSTOMER.INVALID_PARAM_COMBINATION","message": "Indicated parameter combination is invalid"`) + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + + application/json: + + schema: + $ref: '#/components/schemas/ErrorInfo' + examples: + InvalidArgument: + value: + status: 400 + code: INVALID_ARGUMENT + message: Client specified an invalid argument, request body or query param + InvalidParamCombination: + value: + status: 400 + code: KNOW_YOUR_CUSTOMER.INVALID_PARAM_COMBINATION + message: Indicated parameter combination is invalid + + Generic401: + description: Authentication problem with the client request. Unauthorized error. Access Token related errors. + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + + schema: + $ref: '#/components/schemas/ErrorInfo' + examples: + Unauthenticated: + value: + status: 401 + code: UNAUTHENTICATED + message: Request not authenticated due to missing, invalid, or expired credentials + + Generic403: + description: | + Client does not have sufficient permission. + In addition to regular scenario of `PERMISSION_DENIED`, another scenarios may exist: + + - Phone number cannot be deducted from access token context.(`{"code": "KNOW_YOUR_CUSTOMER.INVALID_TOKEN_CONTEXT","message": "Phone number mismatch with access token context"}`) + + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + + application/json: + + schema: + $ref: '#/components/schemas/ErrorInfo' + examples: + PermissionDenied: + value: + status: 403 + code: PERMISSION_DENIED + message: Client does not have sufficient permissions to perform this action + InvalidTokenContext: + value: + status: 403 + code: KNOW_YOUR_CUSTOMER.INVALID_TOKEN_CONTEXT + message: Phone number mismatch with access token context + + Generic404: + description: | + Not Found error. Error if URL is wrong / user is not found. + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + + schema: + $ref: '#/components/schemas/ErrorInfo' + examples: + NotFound: + value: + status: 404 + + code: NOT_FOUND + message: not_found_contractor/not_found + + Generic500: + description: Server error. Problem with MNO's server side. Some processing error within MNO's servers. + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + + schema: + $ref: '#/components/schemas/ErrorInfo' + examples: + ServerError: + value: + status: 500 + code: INTERNAL + message: Server error + + Generic503: + description: Service unavailable. Typically the server is down. Problem with MNO's server side. Any unexpected error within MNO's servers. + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + + schema: + $ref: '#/components/schemas/ErrorInfo' + examples: + ServiceUnavailable: + value: + status: 503 + code: UNAVAILABLE + message: Service unavailable + + Generic504: + description: Request time exceeded. If it happens repeatedly, consider reducing the request complexity + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + + schema: + $ref: '#/components/schemas/ErrorInfo' + example: + status: 504 + code: TIMEOUT + message: Request timeout exceeded. Try later. From 0335b85a8f6ddfaf5943c7f66f3c2544e3b3fec2 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Fri, 16 Feb 2024 10:14:20 +0100 Subject: [PATCH 03/44] Update age-vefification.yaml --- code/API_definitions/age-vefification.yaml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index 2d23343..a2447f8 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -19,26 +19,26 @@ servers: default: http://localhost:9091 description: API root basePath: - default: kyc-ageverification/v0 - description: Base path for the KYC-AgeVerification API + default: kyc-ageverify/v0 + description: Base path for the KYC-AgeVerify API tags: - - name: AgeVerification + - name: AgeVerify description: Operations to verify the age of a user. paths: - /ageverification: + /ageverify: post: tags: - - AgeVerification + - AgeVerify summary: Verify if the age of a user is under the provided age value submitted in order to automatically denied access to gaming, alcohol, or other age-restricted sites. - operationId: KYC_AgeVerification + operationId: KYC_AgeVerify security: - openId: - - know-your-customer:AgeVerification + - know-your-customer:AgeVerify parameters: @@ -52,7 +52,7 @@ paths: schema: $ref: '#/components/schemas/KYC_RequestBody' examples: - AgeVerificationRequestExample: + RequestExample: value: phoneNumber: '+34629255833' age: 18 From ea5d63ab2acee3a3cbff7e8a9bb726f57f0f771d Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Tue, 5 Mar 2024 10:20:09 +0100 Subject: [PATCH 04/44] Update age-vefification.yaml Add firstName and FamilyName attributes to be compared with MNO information --- code/API_definitions/age-vefification.yaml | 29 ++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index a2447f8..f238d29 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -55,6 +55,8 @@ paths: RequestExample: value: phoneNumber: '+34629255833' + giventName: 'Federica' + familyName: 'Sanchez Arjona' age: 18 responses: @@ -73,6 +75,8 @@ paths: KYC_200Example: value: phoneNumber: '+34629255833' + giventNameMatch: 'True' + familyNameMatch: 'True' isVerified: true '400': @@ -127,6 +131,14 @@ components: type: "string" description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, optionally prefixed with '+'. + givenName: + type: "string" + description: First name/given name of the customer. It may include a compound first name or a second/middle name. + + familyName: + type: "string" + description: Surname/family name of the customer. It may include a compound last name or an additional last name. + age: type: "integer" description: age to be verified. @@ -140,6 +152,23 @@ components: type: "string" description: A public identifier addressing a telephone subscription. + + givenNameMatch: + type: "string" + description: Indicates whether First name/given name of the customer matches with the one on the OB systems. + enum: + - 'true' + - 'false' + - 'not_available' + + familyNameMatch: + type: "string" + description: Indicates whether Surname/family name of the customer matches with the one on the OB systems. + enum: + - 'true' + - 'false' + - 'not_available' + isVerified: type: "boolean" default: True From da5d59c441c980ebbc69f8a3ad1b11eb70d95135 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Wed, 6 Mar 2024 14:57:53 +0100 Subject: [PATCH 05/44] Update age-vefification.yaml Addition of MiddleNames --- code/API_definitions/age-vefification.yaml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index f238d29..bdee15b 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -56,6 +56,7 @@ paths: value: phoneNumber: '+34629255833' giventName: 'Federica' + middleNames: 'Sanchez' familyName: 'Sanchez Arjona' age: 18 @@ -76,6 +77,7 @@ paths: value: phoneNumber: '+34629255833' giventNameMatch: 'True' + middleNamesMatch: 'true' familyNameMatch: 'True' isVerified: true @@ -135,6 +137,10 @@ components: type: "string" description: First name/given name of the customer. It may include a compound first name or a second/middle name. + middleNames: + type: string + description: Middle name/s of the customer. + familyName: type: "string" description: Surname/family name of the customer. It may include a compound last name or an additional last name. @@ -161,6 +167,14 @@ components: - 'false' - 'not_available' + middleNamesMatch: + type: string + description: Indicates whether the middle names of the customer matches with the one on the OB systems. + enum: + - 'true' + - 'false' + - 'not_available' + familyNameMatch: type: "string" description: Indicates whether Surname/family name of the customer matches with the one on the OB systems. From 6673fe5f4857f8460d044445f562c5339e9a6296 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Tue, 12 Mar 2024 08:46:32 +0100 Subject: [PATCH 06/44] Update age-vefification.yaml --- code/API_definitions/age-vefification.yaml | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index bdee15b..7fb9417 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -55,7 +55,7 @@ paths: RequestExample: value: phoneNumber: '+34629255833' - giventName: 'Federica' + givenName: 'Federica' middleNames: 'Sanchez' familyName: 'Sanchez Arjona' age: 18 @@ -76,7 +76,7 @@ paths: KYC_200Example: value: phoneNumber: '+34629255833' - giventNameMatch: 'True' + givenNameMatch: 'True' middleNamesMatch: 'true' familyNameMatch: 'True' isVerified: true @@ -126,6 +126,10 @@ components: schemas: KYC_RequestBody: description: "Requested information to be compare with customer personal information" + required: + - "givenName" + - "familyName" + - "age" type: "object" properties: @@ -159,13 +163,12 @@ components: description: A public identifier addressing a telephone subscription. - givenNameMatch: + givenNameMatch:: type: "string" description: Indicates whether First name/given name of the customer matches with the one on the OB systems. enum: - 'true' - 'false' - - 'not_available' middleNamesMatch: type: string @@ -173,7 +176,6 @@ components: enum: - 'true' - 'false' - - 'not_available' familyNameMatch: type: "string" @@ -181,7 +183,6 @@ components: enum: - 'true' - 'false' - - 'not_available' isVerified: type: "boolean" From ae2c024fdfda93e107e280636eeb7940a2b7eb46 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Wed, 27 Mar 2024 09:55:49 +0100 Subject: [PATCH 07/44] Update age-vefification.yaml with Huub (KPN) proposition: assurance level --- code/API_definitions/age-vefification.yaml | 47 +++++++++------------- 1 file changed, 18 insertions(+), 29 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index 7fb9417..34262c8 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -23,7 +23,7 @@ servers: description: Base path for the KYC-AgeVerify API tags: - - name: AgeVerify + - name: Ageverify description: Operations to verify the age of a user. @@ -31,8 +31,8 @@ paths: /ageverify: post: tags: - - AgeVerify - summary: Verify if the age of a user is under the provided age value submitted in order to automatically denied access to gaming, alcohol, or other age-restricted sites. + - Ageverify + summary: Verify if the age of a user is under the provided age value submitted in order to automatically denied access to gaming, alcohol, or other age-restricted sites. There are restrictions applied to the service. User phone number must be the contact's phone number declared in the contract. operationId: KYC_AgeVerify @@ -57,7 +57,8 @@ paths: phoneNumber: '+34629255833' givenName: 'Federica' middleNames: 'Sanchez' - familyName: 'Sanchez Arjona' + familyName: 'Arjona' + email: "FedericaSanchez.Arjona@gmail.com" age: 18 responses: @@ -76,10 +77,9 @@ paths: KYC_200Example: value: phoneNumber: '+34629255833' - givenNameMatch: 'True' - middleNamesMatch: 'true' - familyNameMatch: 'True' + age: 18 isVerified: true + assuranceLeve: 95 '400': $ref: '#/components/responses/Generic400' @@ -149,11 +149,14 @@ components: type: "string" description: Surname/family name of the customer. It may include a compound last name or an additional last name. + email: + type: string + description: Email address of the customer in the RFC specified format (local-part@domain), stored on the OB systems. + age: type: "integer" description: age to be verified. - KYC_ResponseBody: type: "object" properties: @@ -162,33 +165,19 @@ components: type: "string" description: A public identifier addressing a telephone subscription. - - givenNameMatch:: - type: "string" - description: Indicates whether First name/given name of the customer matches with the one on the OB systems. - enum: - - 'true' - - 'false' - - middleNamesMatch: - type: string - description: Indicates whether the middle names of the customer matches with the one on the OB systems. - enum: - - 'true' - - 'false' - - familyNameMatch: - type: "string" - description: Indicates whether Surname/family name of the customer matches with the one on the OB systems. - enum: - - 'true' - - 'false' + age: + type: "integer" + description: age which has been verified. isVerified: type: "boolean" default: True description: Indicates if the age has been verified (True) or if it has not been possible (False). + assuranceLevel: + type: "integer" + description: Assurance level the MNO has to provide a result of the age verification. + ErrorInfo: type: "object" required: From d35564d4ad8043dff93a5ccaff9193a36a59b8ff Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Wed, 10 Apr 2024 15:44:43 +0200 Subject: [PATCH 08/44] Update age-vefification.yaml assuranceLevel is now a enum (Low, Substancial, High) and not a score. --- code/API_definitions/age-vefification.yaml | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index 34262c8..d4d86c9 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -79,8 +79,7 @@ paths: phoneNumber: '+34629255833' age: 18 isVerified: true - assuranceLeve: 95 - + assuranceLeve: 'substancial' '400': $ref: '#/components/responses/Generic400' @@ -175,8 +174,12 @@ components: description: Indicates if the age has been verified (True) or if it has not been possible (False). assuranceLevel: - type: "integer" - description: Assurance level the MNO has to provide a result of the age verification. + type: "string" + description: Assurance level estimated by the MNO on the age verification according to data it hold. + enum: + - 'Low' + - 'Substancial' + - 'High' ErrorInfo: type: "object" From 52f2ca6c55cf9404223420e49c4c1db1f0bdc5c3 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Wed, 22 May 2024 16:22:29 +0200 Subject: [PATCH 09/44] Update age-vefification.yaml --- code/API_definitions/age-vefification.yaml | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index d4d86c9..2342ff7 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -169,9 +169,15 @@ components: description: age which has been verified. isVerified: - type: "boolean" + type: "string" default: True - description: Indicates if the age has been verified (True) or if it has not been possible (False). + description: Indicates if the age has been verified (True) or not. + enum: + - 'True' + - 'False' + - 'Unverified' + - 'Not_Available' + - 'Insufficient_Data' assuranceLevel: type: "string" From 754c2e04c0d8d053fc38b5cd325534381839d301 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Wed, 29 May 2024 14:40:53 +0200 Subject: [PATCH 10/44] Update age-vefification.yaml --- code/API_definitions/age-vefification.yaml | 49 +++++++++++++++------- 1 file changed, 35 insertions(+), 14 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index 2342ff7..b5998dc 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -55,9 +55,14 @@ paths: RequestExample: value: phoneNumber: '+34629255833' - givenName: 'Federica' - middleNames: 'Sanchez' - familyName: 'Arjona' + idDocument: 66666666q + name: Federica Sanchez Arjona + giventName: Federica + familyName: Sanchez Arjona + nameKanaHankaku: federica + nameKanaZenkaku: Ｆｅｄｅｒｉｃａ + middleNames: Sanchez + familyNameAtBirth: YYYY email: "FedericaSanchez.Arjona@gmail.com" age: 18 @@ -135,18 +140,38 @@ components: phoneNumber: type: "string" description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, optionally prefixed with '+'. + + idDocument: + type: string + description: Id number associated to the official identity document in the country. It may contain alphanumeric characters. + + name: + type: string + description: Complete name of the customer, usually composed of first/given name and last/family/sur- name in a country. Depending on the country, the order of first/give name and last/family/sur- name varies, and middle name could be included. It can use givenName, middleNames, familyName and/or familyNameAtBirth. For example, in ESP, name+familyName; in NLD, it can be name+middleNames+familyName or name+middleNames+familyNameAtBirth, etc. givenName: - type: "string" - description: First name/given name of the customer. It may include a compound first name or a second/middle name. + type: string + description: First/given name or compound first/given name of the customer. + + familyName: + type: string + description: Last name, family name, or surname of the customer. + + nameKanaHankaku: + type: string + description: Complete name of the customer in Hankaku-Kana format (reading of name) for Japan. + + nameKanaZenkaku: + type: string + description: Complete name of the customer in Zenkaku-Kana format (reading of name) for Japan. middleNames: type: string description: Middle name/s of the customer. - familyName: - type: "string" - description: Surname/family name of the customer. It may include a compound last name or an additional last name. + familyNameAtBirth: + type: string + description: Last/family/sur- name at birth of the customer. email: type: string @@ -179,13 +204,9 @@ components: - 'Not_Available' - 'Insufficient_Data' - assuranceLevel: - type: "string" + score: + type: "integer" description: Assurance level estimated by the MNO on the age verification according to data it hold. - enum: - - 'Low' - - 'Substancial' - - 'High' ErrorInfo: type: "object" From 82647d144e8cad81393b28f3c909989dcc79b82d Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Wed, 29 May 2024 14:41:48 +0200 Subject: [PATCH 11/44] Update age-vefification.yaml --- code/API_definitions/age-vefification.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index b5998dc..c0d7001 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -84,7 +84,7 @@ paths: phoneNumber: '+34629255833' age: 18 isVerified: true - assuranceLeve: 'substancial' + assuranceLeve: 90 '400': $ref: '#/components/responses/Generic400' From 830e390561f47f6b5bc40aa95ffa41dca13445e4 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Wed, 29 May 2024 14:43:50 +0200 Subject: [PATCH 12/44] Update age-vefification.yaml --- code/API_definitions/age-vefification.yaml | 4 ---- 1 file changed, 4 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index c0d7001..b35fc4a 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -130,10 +130,6 @@ components: schemas: KYC_RequestBody: description: "Requested information to be compare with customer personal information" - required: - - "givenName" - - "familyName" - - "age" type: "object" properties: From 4bd8a34c1eb9c20ea7fb9a922b514aef3fb4cc77 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Mon, 10 Jun 2024 11:02:52 +0200 Subject: [PATCH 13/44] Update age-vefification.yaml --- code/API_definitions/age-vefification.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index b35fc4a..b1e5a19 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -83,8 +83,8 @@ paths: value: phoneNumber: '+34629255833' age: 18 - isVerified: true - assuranceLeve: 90 + ageVerified: true + identityMatchScore: 90 '400': $ref: '#/components/responses/Generic400' @@ -189,7 +189,7 @@ components: type: "integer" description: age which has been verified. - isVerified: + ageVerified: type: "string" default: True description: Indicates if the age has been verified (True) or not. @@ -200,7 +200,7 @@ components: - 'Not_Available' - 'Insufficient_Data' - score: + identityMatchScore: type: "integer" description: Assurance level estimated by the MNO on the age verification according to data it hold. From c4863dd5ed09b75d028a207ad78fcc066823dd84 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Tue, 18 Jun 2024 15:59:52 +0200 Subject: [PATCH 14/44] Update age-vefification.yaml --- code/API_definitions/age-vefification.yaml | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index b1e5a19..09f7c04 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -57,7 +57,7 @@ paths: phoneNumber: '+34629255833' idDocument: 66666666q name: Federica Sanchez Arjona - giventName: Federica + givenName: Federica familyName: Sanchez Arjona nameKanaHankaku: federica nameKanaZenkaku: Ｆｅｄｅｒｉｃａ @@ -138,39 +138,39 @@ components: description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, optionally prefixed with '+'. idDocument: - type: string + type: "string" description: Id number associated to the official identity document in the country. It may contain alphanumeric characters. name: - type: string + type: "string" description: Complete name of the customer, usually composed of first/given name and last/family/sur- name in a country. Depending on the country, the order of first/give name and last/family/sur- name varies, and middle name could be included. It can use givenName, middleNames, familyName and/or familyNameAtBirth. For example, in ESP, name+familyName; in NLD, it can be name+middleNames+familyName or name+middleNames+familyNameAtBirth, etc. givenName: - type: string + type: "string" description: First/given name or compound first/given name of the customer. familyName: - type: string + type: "string" description: Last name, family name, or surname of the customer. nameKanaHankaku: - type: string + type: "string" description: Complete name of the customer in Hankaku-Kana format (reading of name) for Japan. nameKanaZenkaku: - type: string + type: "string" description: Complete name of the customer in Zenkaku-Kana format (reading of name) for Japan. middleNames: - type: string + type: "string" description: Middle name/s of the customer. familyNameAtBirth: - type: string + type: "string" description: Last/family/sur- name at birth of the customer. email: - type: string + type: "string" description: Email address of the customer in the RFC specified format (local-part@domain), stored on the OB systems. age: From 007c6c0aec9bb6a14adcf6ffc5dfbf050c6a3be3 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Tue, 18 Jun 2024 16:09:38 +0200 Subject: [PATCH 15/44] Update age-vefification.yaml --- code/API_definitions/age-vefification.yaml | 5 ----- 1 file changed, 5 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index 09f7c04..da7bc90 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -81,7 +81,6 @@ paths: examples: KYC_200Example: value: - phoneNumber: '+34629255833' age: 18 ageVerified: true identityMatchScore: 90 @@ -181,10 +180,6 @@ components: type: "object" properties: - phoneNumber: - type: "string" - description: A public identifier addressing a telephone subscription. - age: type: "integer" description: age which has been verified. From abc40934063e6b77ea2ba583b1f2e971447f4f71 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Wed, 19 Jun 2024 10:16:41 +0200 Subject: [PATCH 16/44] Update age-vefification.yaml --- code/API_definitions/age-vefification.yaml | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index da7bc90..ab6933f 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -59,8 +59,6 @@ paths: name: Federica Sanchez Arjona givenName: Federica familyName: Sanchez Arjona - nameKanaHankaku: federica - nameKanaZenkaku: Ｆｅｄｅｒｉｃａ middleNames: Sanchez familyNameAtBirth: YYYY email: "FedericaSanchez.Arjona@gmail.com" @@ -152,13 +150,6 @@ components: type: "string" description: Last name, family name, or surname of the customer. - nameKanaHankaku: - type: "string" - description: Complete name of the customer in Hankaku-Kana format (reading of name) for Japan. - - nameKanaZenkaku: - type: "string" - description: Complete name of the customer in Zenkaku-Kana format (reading of name) for Japan. middleNames: type: "string" @@ -193,11 +184,10 @@ components: - 'False' - 'Unverified' - 'Not_Available' - - 'Insufficient_Data' identityMatchScore: type: "integer" - description: Assurance level estimated by the MNO on the age verification according to data it hold. + description: Aggregate score of user's identity match result. ErrorInfo: type: "object" From b4a2009fb0743f2e7eab7a230d901ec21b02ca72 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Wed, 9 Oct 2024 16:44:17 +0200 Subject: [PATCH 17/44] Update age-vefification.yaml Corrections, updated Design and description --- code/API_definitions/age-vefification.yaml | 263 ++++++++++++++++++--- 1 file changed, 227 insertions(+), 36 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index ab6933f..59d53f9 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -2,25 +2,117 @@ openapi: 3.0.3 info: title: Know Your Customer Age Verification - termsOfService: http://swagger.io/terms/ + description: | + + # Summary + This API provides the customer with the ability to check if the user of the line is older than a provided age, in order to provide API customer's age-restricted services, access to its age-restricted website etc.. + + # Authorization and authentication + + The "Camara Security and Interoperability Profile" provides details on how a client requests an access token. Please refer to Identify and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the Profile. + + Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation. + + It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control. + + # API functionality + + The API defines one service endpoint: + + - `POST /ageverify` + + Takes the network subscription identifier (e.g. the mobile phone number for a mobile network subscriber) and check the age of the user is older than the age's threshold in the request. + If infotrmation of the user's identity such as `givenName`, `familyName`, `address` match with information held by the MNO. + + + ## Inputs + + The endpoint request body is a JSON object with the following parameters: + - `phoneNumber`: The network subscription identifier (i.e. the phone number of the subscriber). This field is only required if no network subscription identifier is associated with the access token. + - `ageThreshold`: The date's threshold from which the age of the user must be compared. + + + - `givenName`, `familyName`, `address`,`etc.` user's information to be checked in order to confirm that the user is the contract's owner. + + + ## Outputs + + If successful, a JSON object is returned containing the following data: + - `ageThreshold`: The date's threshold from which the age of the user must be compared. + - `ageVerified`: true when the age of the user is older than the age threshold, otherwise false if not. unverified if the MNO has never verified whether this is valid or not. + - `identityMatchScore`: the overall match score of identity information provided in the request compared to what MNO holds. + + An example of a JSON response object is as follows: + ``` + { + "phoneNumber": '+34629255833', + "ageThreshold": 18, + "idDocument": '66666666q', + "name": 'Federica Sanchez Arjona', + "givenName": 'Federica', + "familyName": 'Sanchez Arjona', + "middleNames": 'Sanchez', + "familyNameAtBirth": 'YYYY', + "birthdate": '1978-08-22', + "email": 'edericaSanchez.Arjona@gmail.com' + } + ``` + + ## Errors + + If the authentication token is not valid, a `401 UNAUTHENTICATED` error is returned + + If the API call contain a formatting or other error, a `400 INVALID_ARGUMENT` error is returned. + + If the network subscription cannot be identified from the provided parameters (e.g. the subscription identifier is not associated with any customer of the CSP), a `404 DEVICE_NOT_FOUND` error is returned. + + If the API consumer has a valid access token but is not authorised to obtain tenure information for the specified network subscription, then a `403 PERMISSION_DENIED` error is returned. + + Other errors may be returned as specified below. + + # Identifying a device from the access token + + This specification defines the `phoneNumber` field as optional in API requests, specifically in cases where the API is accessed using a 3-legged access token, and the device can be uniquely identified by the token. This approach simplifies API usage for API consumers by relying on the device information associated with the access token used to invoke the API. + + ## Handling of device information: + + ### Optional phoneNumber for 3-legged tokens: + + - When using a 3-legged access token, the device associated with the access token must be considered as the device for the API request. This means that the phoneNumber is not required in the request, and if included it must identify the same device, therefore **it is recommended NOT to include it in these scenarios** to simplify the API usage and avoid additional validations. + + ### Validation mechanism: + + - The server will extract the device identification from the access token, if available. + - If the API request additionally includes a `phoneNumber` parameter when using a 3-legged access token, the API will validate that the device identifier provided matches the one associated with the access token. + - If there is a mismatch, the API will respond with a `403 INVALID_TOKEN_CONTEXT` error, indicating that the device information in the request does not match the token. + + ### Error handling for unidentifiable devices: + + - If the `phoneNumber` parameter is not included in the request and the device information cannot be derived from the 3-legged access token, the server will return a `422 UNIDENTIFIABLE_DEVICE` error. + + ### Restrictions for tokens without an associated authenticated identifier: + + - For scenarios which do not have a single device identifier associated to the token during the authentication flow, e.g. 2-legged access tokens, the `phoneNumber` parameter MUST be provided in the API request. This ensures that the device identification is explicit and valid for each API call made with these tokens. + + # Further info and support + + (FAQs will be added in a later version of the documentation) + + + version: wip contact: - email: project-email@sample.com + email: sp-kyc@lists.camaraproject.org license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - version: 0.1.0-wip - - servers: - - url: '{apiRoot}/{basePath}' + - url: "{apiRoot}/kyc-ageverify/vwip" variables: apiRoot: - default: http://localhost:9091 + default: https://localhost:443 description: API root - basePath: - default: kyc-ageverify/v0 - description: Base path for the KYC-AgeVerify API + tags: - name: Ageverify @@ -61,8 +153,9 @@ paths: familyName: Sanchez Arjona middleNames: Sanchez familyNameAtBirth: YYYY + birthdate: '1978-08-22' email: "FedericaSanchez.Arjona@gmail.com" - age: 18 + ageThreshold: 18 responses: '200': @@ -79,28 +172,30 @@ paths: examples: KYC_200Example: value: - age: 18 + ageThreshold: 18 ageVerified: true identityMatchScore: 90 - '400': + "400": $ref: '#/components/responses/Generic400' - - '401': + "401": $ref: '#/components/responses/Generic401' - - '403': + "403": $ref: '#/components/responses/Generic403' - - '404': + "404": $ref: '#/components/responses/Generic404' - - '500': + "406": + $ref: '#/components/responses/Generic406' + "415": + $ref: '#/components/responses/Generic415' + "422": + $ref: '#/components/responses/Generic422' + "429": + $ref: '#/components/responses/Generic429' + "500": $ref: '#/components/responses/Generic500' - - '503': + "503": $ref: '#/components/responses/Generic503' - - '504': + "504": $ref: '#/components/responses/Generic504' components: @@ -128,7 +223,9 @@ components: KYC_RequestBody: description: "Requested information to be compare with customer personal information" type: "object" - + required: + - ageThreshold + properties: phoneNumber: type: "string" @@ -159,35 +256,42 @@ components: type: "string" description: Last/family/sur- name at birth of the customer. + birthdate: + type: string + description: The birthdate of the customer, in ISO 8601 calendar date format (YYYY-MM-DD). + email: type: "string" description: Email address of the customer in the RFC specified format (local-part@domain), stored on the OB systems. - age: + ageThreshold: type: "integer" description: age to be verified. KYC_ResponseBody: type: "object" + required: + - ageThreshold + - ageVerified + properties: - age: + ageThreshold: type: "integer" - description: age which has been verified. + description: age threshold which has been verified. ageVerified: type: "string" - default: True - description: Indicates if the age has been verified (True) or not. + description: Indicates if the age has been verified (true) or not (false). If age information is not available not_available is returned, else unverified indicates that MNO has not verified the validity of the information it holds. enum: - - 'True' - - 'False' - - 'Unverified' - - 'Not_Available' + - 'true' + - 'false' + - 'unverified' + - 'not_Available' identityMatchScore: type: "integer" - description: Aggregate score of user's identity match result. + description: Aggregate score of user's identity match result i =n case of information have been included in the request. ErrorInfo: type: "object" @@ -298,6 +402,93 @@ components: code: NOT_FOUND message: not_found_contractor/not_found + Generic406: + description: Not Acceptable + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_406_NOT_ACCEPTABLE: + description: API Server does not accept the media type (`Accept-*` header) indicated by API client + value: + status: 406 + code: NOT_ACCEPTABLE + message: The server cannot produce a response matching the content requested by the client through `Accept-*` headers. + + Generic415: + description: Unsupported Media Type + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_415_UNSUPPORTED_MEDIA_TYPE: + description: Payload format of the request is in an unsupported format by the Server. Should not happen + value: + status: 415 + code: UNSUPPORTED_MEDIA_TYPE + message: The server refuses to accept the request because the payload format is in an unsupported format. + + Generic422: + description: Unprocessable Content + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH: + description: Inconsistency between device identifiers not pointing to the same device + value: + status: 422 + code: DEVICE_IDENTIFIERS_MISMATCH + message: Provided device identifiers are not consistent. + GENERIC_422_DEVICE_NOT_APPLICABLE: + description: Service is not available for the provided device + value: + status: 422 + code: DEVICE_NOT_APPLICABLE + message: The service is not available for the provided device. + GENERIC_422_UNIDENTIFIABLE_DEVICE: + description: No identifier provided for any device + value: + status: 422 + code: UNIDENTIFIABLE_DEVICE + message: No identifier provided for any device + + Generic429: + description: Too Many Requests + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_429_QUOTA_EXCEEDED: + description: Request is rejected due to exceeding a business quota limit + value: + status: 429 + code: QUOTA_EXCEEDED + message: Either out of resource quota or reaching rate limiting. + GENERIC_429_TOO_MANY_REQUESTS: + description: API Server request limit is overpassed + value: + status: 429 + code: TOO_MANY_REQUESTS + message: Either out of resource quota or reaching rate limiting. + + Generic500: description: Server error. Problem with MNO's server side. Some processing error within MNO's servers. headers: From dd5d70113f7b7cc78f62ab804d50e9d019d2a7df Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Thu, 10 Oct 2024 10:44:13 +0200 Subject: [PATCH 18/44] Update age-vefification.yaml Corrections of few mistakes --- code/API_definitions/age-vefification.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index 59d53f9..f69acea 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -287,11 +287,11 @@ components: - 'true' - 'false' - 'unverified' - - 'not_Available' + - 'not_available' identityMatchScore: type: "integer" - description: Aggregate score of user's identity match result i =n case of information have been included in the request. + description: An aggregate match score of user's identity when available in the request body. ErrorInfo: type: "object" From 1f55416660bcfef124e772ddaf4d8bfef960c13e Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Tue, 22 Oct 2024 10:38:39 +0200 Subject: [PATCH 19/44] Update age-vefification.yaml --- code/API_definitions/age-vefification.yaml | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index f69acea..47b5b26 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -38,8 +38,8 @@ info: ## Outputs If successful, a JSON object is returned containing the following data: - - `ageThreshold`: The date's threshold from which the age of the user must be compared. - - `ageVerified`: true when the age of the user is older than the age threshold, otherwise false if not. unverified if the MNO has never verified whether this is valid or not. + - `ageVerified`: true if the information provided was checked against another form of official identification, otherwise false. + - `ageCheck`: true when the age of the user is older than the age threshold, otherwise false if not. unverified if the MNO has never verified whether this is valid or not. - `identityMatchScore`: the overall match score of identity information provided in the request compared to what MNO holds. An example of a JSON response object is as follows: @@ -271,16 +271,15 @@ components: KYC_ResponseBody: type: "object" required: - - ageThreshold - - ageVerified + - ageCheck properties: - ageThreshold: - type: "integer" - description: age threshold which has been verified. - ageVerified: + type: "boolean" + description: Indicates if the information provided was checked against another form of official identification held by the MNO. + + ageCheck: type: "string" description: Indicates if the age has been verified (true) or not (false). If age information is not available not_available is returned, else unverified indicates that MNO has not verified the validity of the information it holds. enum: From 6b6bdb022ee4efc49f3580326d67e6079882c74c Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Tue, 22 Oct 2024 10:42:14 +0200 Subject: [PATCH 20/44] Update age-vefification.yaml Add corrections proposed by Toshi and Huub --- code/API_definitions/age-vefification.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index 47b5b26..1b7977d 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -172,8 +172,8 @@ paths: examples: KYC_200Example: value: - ageThreshold: 18 ageVerified: true + ageCheck: true identityMatchScore: 90 "400": $ref: '#/components/responses/Generic400' From e6a6acfd1483e1a922d3a5abe8ed1866a866bfa0 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Thu, 7 Nov 2024 12:35:10 +0100 Subject: [PATCH 21/44] Update age-vefification.yaml --- code/API_definitions/age-vefification.yaml | 24 ++++++++-------------- 1 file changed, 9 insertions(+), 15 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index 1b7977d..6e76bda 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -439,30 +439,24 @@ components: description: Unprocessable Content headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: "#/components/headers/x-correlator" content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" examples: - GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH: - description: Inconsistency between device identifiers not pointing to the same device - value: - status: 422 - code: DEVICE_IDENTIFIERS_MISMATCH - message: Provided device identifiers are not consistent. - GENERIC_422_DEVICE_NOT_APPLICABLE: - description: Service is not available for the provided device + GENERIC_422_NOT_SUPPORTED: + description: Not Supported value: status: 422 - code: DEVICE_NOT_APPLICABLE - message: The service is not available for the provided device. - GENERIC_422_UNIDENTIFIABLE_DEVICE: - description: No identifier provided for any device + code: NOT_SUPPORTED + message: Service not supported for this phoneNumber + UNIDENTIFIABLE_PHONE_NUMBER: + description: The phone number is not included in the request and the phone number information cannot be derived from the 3-legged access token value: status: 422 - code: UNIDENTIFIABLE_DEVICE - message: No identifier provided for any device + code: UNIDENTIFIABLE_PHONE_NUMBER + message: The phone number cannot be identified Generic429: description: Too Many Requests From 9cac56f8ae9603104678e2a69f27d7488d06fa69 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Thu, 7 Nov 2024 12:44:29 +0100 Subject: [PATCH 22/44] Update age-vefification.yaml --- code/API_definitions/age-vefification.yaml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index 6e76bda..2910366 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -247,7 +247,6 @@ components: type: "string" description: Last name, family name, or surname of the customer. - middleNames: type: "string" description: Middle name/s of the customer. @@ -259,10 +258,10 @@ components: birthdate: type: string description: The birthdate of the customer, in ISO 8601 calendar date format (YYYY-MM-DD). - + email: - type: "string" - description: Email address of the customer in the RFC specified format (local-part@domain), stored on the OB systems. + type: string + description: Email address of the customer in the RFC specified format (local-part@domain). ageThreshold: type: "integer" From 54ec9980000fc8b69585af0d31d4464678b74c2a Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Fri, 8 Nov 2024 11:22:32 +0100 Subject: [PATCH 23/44] Update age-vefification.yaml Add new error messages for HTTP 422, add verifiedStatus --- code/API_definitions/age-vefification.yaml | 24 ++++++++++------------ 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index 2910366..e01152e 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -22,24 +22,22 @@ info: - `POST /ageverify` Takes the network subscription identifier (e.g. the mobile phone number for a mobile network subscriber) and check the age of the user is older than the age's threshold in the request. - If infotrmation of the user's identity such as `givenName`, `familyName`, `address` match with information held by the MNO. + If information of the user's identity such as `givenName`, `familyName`, `address` match with information held by the MNO. ## Inputs The endpoint request body is a JSON object with the following parameters: - - `phoneNumber`: The network subscription identifier (i.e. the phone number of the subscriber). This field is only required if no network subscription identifier is associated with the access token. - - `ageThreshold`: The date's threshold from which the age of the user must be compared. + - `phoneNumber`: The network subscription identifier (i.e. the phone number of the subscriber). [Only required in case a 2-legged flow has been agreed between API Provider and API Consumer; otherwise, none] + - `ageThreshold`: The date's threshold from which the age of the user must be compared. [Required] + - any of `idDocument`, `name`, `givenName`, `familyName`, `middieNames`, `familyNameAtBirth`, `birthdate`, `email`; user's information to be checked in order to confirm that the user is the contract's owner [Optional] - - - `givenName`, `familyName`, `address`,`etc.` user's information to be checked in order to confirm that the user is the contract's owner. - ## Outputs If successful, a JSON object is returned containing the following data: - - `ageVerified`: true if the information provided was checked against another form of official identification, otherwise false. - `ageCheck`: true when the age of the user is older than the age threshold, otherwise false if not. unverified if the MNO has never verified whether this is valid or not. + - `verifiedStatus`: true if the information provided was checked against another form of official identification, otherwise false. - `identityMatchScore`: the overall match score of identity information provided in the request compared to what MNO holds. An example of a JSON response object is as follows: @@ -130,7 +128,7 @@ paths: security: - openId: - - know-your-customer:AgeVerify + - kyc-ageverify:ageVerify parameters: @@ -172,8 +170,8 @@ paths: examples: KYC_200Example: value: - ageVerified: true ageCheck: true + verifiedStatus: true identityMatchScore: 90 "400": $ref: '#/components/responses/Generic400' @@ -274,10 +272,6 @@ components: properties: - ageVerified: - type: "boolean" - description: Indicates if the information provided was checked against another form of official identification held by the MNO. - ageCheck: type: "string" description: Indicates if the age has been verified (true) or not (false). If age information is not available not_available is returned, else unverified indicates that MNO has not verified the validity of the information it holds. @@ -287,6 +281,10 @@ components: - 'unverified' - 'not_available' + verifiedStatus: + type: "boolean" + description: Indicates if the information provided was checked against another form of official identification held by the MNO. + identityMatchScore: type: "integer" description: An aggregate match score of user's identity when available in the request body. From 35eeb396ed6f96cffe6c160b7645166f6f99d7f4 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Thu, 14 Nov 2024 10:32:54 +0100 Subject: [PATCH 24/44] Update age-vefification.yaml Update of the response JSON example --- code/API_definitions/age-vefification.yaml | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index e01152e..8e1d86d 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -40,22 +40,6 @@ info: - `verifiedStatus`: true if the information provided was checked against another form of official identification, otherwise false. - `identityMatchScore`: the overall match score of identity information provided in the request compared to what MNO holds. - An example of a JSON response object is as follows: - ``` - { - "phoneNumber": '+34629255833', - "ageThreshold": 18, - "idDocument": '66666666q', - "name": 'Federica Sanchez Arjona', - "givenName": 'Federica', - "familyName": 'Sanchez Arjona', - "middleNames": 'Sanchez', - "familyNameAtBirth": 'YYYY', - "birthdate": '1978-08-22', - "email": 'edericaSanchez.Arjona@gmail.com' - } - ``` - ## Errors If the authentication token is not valid, a `401 UNAUTHENTICATED` error is returned From a9ad64da763edd6f121c2d4cc48062819a23091f Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Mon, 25 Nov 2024 16:30:04 +0100 Subject: [PATCH 25/44] Update age-vefification.yaml Updates according to propositions --- code/API_definitions/age-vefification.yaml | 30 ++++++++++------------ 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index 8e1d86d..798a5dd 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -28,7 +28,7 @@ info: ## Inputs The endpoint request body is a JSON object with the following parameters: - - `phoneNumber`: The network subscription identifier (i.e. the phone number of the subscriber). [Only required in case a 2-legged flow has been agreed between API Provider and API Consumer; otherwise, none] + - `phoneNumber`: The network subscription identifier (i.e. the phone number of the subscriber). [Required only in case a 2-legged flow has been agreed between API Provider and API Consumer; otherwise, none] - `ageThreshold`: The date's threshold from which the age of the user must be compared. [Required] - any of `idDocument`, `name`, `givenName`, `familyName`, `middieNames`, `familyNameAtBirth`, `birthdate`, `email`; user's information to be checked in order to confirm that the user is the contract's owner [Optional] @@ -36,7 +36,7 @@ info: ## Outputs If successful, a JSON object is returned containing the following data: - - `ageCheck`: true when the age of the user is older than the age threshold, otherwise false if not. unverified if the MNO has never verified whether this is valid or not. + - `ageCheck`: Indicate 'true' when the age of the user is the same age or older than the age threshold (age >= age threshold), and 'false' if not (age < age threshold). Otherwise, 'not_available'. - `verifiedStatus`: true if the information provided was checked against another form of official identification, otherwise false. - `identityMatchScore`: the overall match score of identity information provided in the request compared to what MNO holds. @@ -60,17 +60,12 @@ info: ### Optional phoneNumber for 3-legged tokens: - - When using a 3-legged access token, the device associated with the access token must be considered as the device for the API request. This means that the phoneNumber is not required in the request, and if included it must identify the same device, therefore **it is recommended NOT to include it in these scenarios** to simplify the API usage and avoid additional validations. + - When using a 3-legged access token, the device associated with the access token must be considered as the device for the API request. This means that the phoneNumber is not required in the request, and if included it must be neglected to simplify the API usage and avoid additional validations. - ### Validation mechanism: - - - The server will extract the device identification from the access token, if available. - - If the API request additionally includes a `phoneNumber` parameter when using a 3-legged access token, the API will validate that the device identifier provided matches the one associated with the access token. - - If there is a mismatch, the API will respond with a `403 INVALID_TOKEN_CONTEXT` error, indicating that the device information in the request does not match the token. ### Error handling for unidentifiable devices: - - If the `phoneNumber` parameter is not included in the request and the device information cannot be derived from the 3-legged access token, the server will return a `422 UNIDENTIFIABLE_DEVICE` error. + - If the `phoneNumber` cannot be derived from the 3-legged access token, the server will return a `422 UNIDENTIFIABLE_DEVICE` error. ### Restrictions for tokens without an associated authenticated identifier: @@ -128,7 +123,8 @@ paths: examples: RequestExample: value: - phoneNumber: '+34629255833' + ageThreshold: 18 + phoneNumber: '+34629255833' # Note: Only required in case a 2-legged flow has been agreed between API Provider and API Consumer; otherwise, do not include phoneNumber idDocument: 66666666q name: Federica Sanchez Arjona givenName: Federica @@ -137,7 +133,6 @@ paths: familyNameAtBirth: YYYY birthdate: '1978-08-22' email: "FedericaSanchez.Arjona@gmail.com" - ageThreshold: 18 responses: '200': @@ -209,6 +204,13 @@ components: - ageThreshold properties: + + ageThreshold: + type: "integer" + minimum: 0 + maximum: 120 + description: age to be verified. + phoneNumber: type: "string" description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, optionally prefixed with '+'. @@ -245,9 +247,6 @@ components: type: string description: Email address of the customer in the RFC specified format (local-part@domain). - ageThreshold: - type: "integer" - description: age to be verified. KYC_ResponseBody: type: "object" @@ -258,12 +257,11 @@ components: ageCheck: type: "string" - description: Indicates if the age has been verified (true) or not (false). If age information is not available not_available is returned, else unverified indicates that MNO has not verified the validity of the information it holds. + description: Indicate 'true' when the age of the user is the same age or older than the age threshold (age >= age threshold), and 'false' if not (age < age threshold). Otherwise, 'not_available'. enum: - 'true' - 'false' - 'unverified' - - 'not_available' verifiedStatus: type: "boolean" From a7526d1abd33d495b69cee6e6ef703c6eb3faa02 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Tue, 26 Nov 2024 13:41:33 +0100 Subject: [PATCH 26/44] Update code/API_definitions/age-vefification.yaml Co-authored-by: Fernando Prado Cabrillo --- code/API_definitions/age-vefification.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index 798a5dd..df2239f 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -261,7 +261,7 @@ components: enum: - 'true' - 'false' - - 'unverified' + - 'not_available' verifiedStatus: type: "boolean" From 6b505d20a9025de350285a96d89cacaededa6ddc Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Tue, 26 Nov 2024 13:42:23 +0100 Subject: [PATCH 27/44] Update code/API_definitions/age-vefification.yaml Co-authored-by: Fernando Prado Cabrillo --- code/API_definitions/age-vefification.yaml | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index df2239f..bd3174c 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -212,8 +212,11 @@ components: description: age to be verified. phoneNumber: - type: "string" - description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, optionally prefixed with '+'. + description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. + type: string + pattern: '^\+[1-9][0-9]{4,14}$' + example: "+123456789" + idDocument: type: "string" From d645e582b1f85dd69dc7a3299ac4e1f22dc27449 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Wed, 27 Nov 2024 14:49:35 +0100 Subject: [PATCH 28/44] Update code/API_definitions/age-vefification.yaml Co-authored-by: Fernando Prado Cabrillo --- code/API_definitions/age-vefification.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index bd3174c..d995e22 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -308,11 +308,13 @@ components: schema: $ref: '#/components/schemas/ErrorInfo' examples: - InvalidArgument: + GENERIC_400_INVALID_ARGUMENT: + description: Invalid Argument. Generic Syntax Exception value: status: 400 code: INVALID_ARGUMENT - message: Client specified an invalid argument, request body or query param + message: Client specified an invalid argument, request body or query param. + InvalidParamCombination: value: status: 400 From 81ff0fc830ec812960ce65e022b3802b9b33cd0e Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Wed, 27 Nov 2024 14:50:17 +0100 Subject: [PATCH 29/44] Update code/API_definitions/age-vefification.yaml Co-authored-by: Fernando Prado Cabrillo --- code/API_definitions/age-vefification.yaml | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index d995e22..cae0fa4 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -332,11 +332,19 @@ components: schema: $ref: '#/components/schemas/ErrorInfo' examples: - Unauthenticated: + GENERIC_401_UNAUTHENTICATED: + description: Request cannot be authenticated value: status: 401 code: UNAUTHENTICATED - message: Request not authenticated due to missing, invalid, or expired credentials + 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. + Generic403: description: | From e9029f2b66c5fcb68fd4f0b3934605e7c48dd1c8 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Wed, 27 Nov 2024 14:51:57 +0100 Subject: [PATCH 30/44] Update code/API_definitions/age-vefification.yaml Co-authored-by: Fernando Prado Cabrillo --- code/API_definitions/age-vefification.yaml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index cae0fa4..935ffd4 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -386,12 +386,13 @@ components: schema: $ref: '#/components/schemas/ErrorInfo' examples: - NotFound: + GENERIC_404_NOT_FOUND: + description: Resource is not found value: status: 404 - code: NOT_FOUND - message: not_found_contractor/not_found + message: The specified resource is not found. + Generic406: description: Not Acceptable From 0f344ce1c38dc44eb99f1f7d9539afa76a3ee624 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Wed, 27 Nov 2024 14:52:36 +0100 Subject: [PATCH 31/44] Update code/API_definitions/age-vefification.yaml Co-authored-by: Fernando Prado Cabrillo --- code/API_definitions/age-vefification.yaml | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index 935ffd4..1801d39 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -363,16 +363,19 @@ components: schema: $ref: '#/components/schemas/ErrorInfo' examples: - PermissionDenied: + GENERIC_403_PERMISSION_DENIED: + description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security value: status: 403 code: PERMISSION_DENIED - message: Client does not have sufficient permissions to perform this action - InvalidTokenContext: + message: Client does not have sufficient permissions to perform this action. + GENERIC_403_INVALID_TOKEN_CONTEXT: + description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token value: status: 403 - code: KNOW_YOUR_CUSTOMER.INVALID_TOKEN_CONTEXT - message: Phone number mismatch with access token context + code: INVALID_TOKEN_CONTEXT + message: "phoneNumber is not consistent with access token." + Generic404: description: | From ee4538f82cd229778cf17cb80fdb156e3cad7eb3 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Wed, 27 Nov 2024 14:53:17 +0100 Subject: [PATCH 32/44] Update code/API_definitions/age-vefification.yaml Co-authored-by: Fernando Prado Cabrillo --- code/API_definitions/age-vefification.yaml | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index 1801d39..1848a20 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -441,18 +441,19 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" examples: - GENERIC_422_NOT_SUPPORTED: - description: Not Supported + GENERIC_422_UNSUPPORTED_IDENTIFIER: + description: None of the provided identifiers is supported by the implementation value: status: 422 - code: NOT_SUPPORTED - message: Service not supported for this phoneNumber - UNIDENTIFIABLE_PHONE_NUMBER: - description: The phone number is not included in the request and the phone number information cannot be derived from the 3-legged access token + code: UNSUPPORTED_IDENTIFIER + message: The identifier provided is not supported. + GENERIC_422_MISSING_IDENTIFIER: + description: The identifier is not included in the request and the identifier information cannot be derived from the 3-legged access token value: status: 422 - code: UNIDENTIFIABLE_PHONE_NUMBER - message: The phone number cannot be identified + code: MISSING_IDENTIFIER + message: The phone number cannot be identified. + Generic429: description: Too Many Requests From 5d4be806dc63161fafd82a559f4b68659d22aad8 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Thu, 28 Nov 2024 15:56:12 +0100 Subject: [PATCH 33/44] Update code/API_definitions/age-vefification.yaml Co-authored-by: Fernando Prado Cabrillo --- code/API_definitions/age-vefification.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index 1848a20..6e76f18 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -213,9 +213,9 @@ components: phoneNumber: description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. - type: string - pattern: '^\+[1-9][0-9]{4,14}$' - example: "+123456789" + type: string + pattern: '^\+[1-9][0-9]{4,14}$' + example: "+123456789" idDocument: From 71fe78d326c35e8b3f41f2f1c98566b81361154b Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Thu, 28 Nov 2024 15:56:51 +0100 Subject: [PATCH 34/44] Update code/API_definitions/age-vefification.yaml Co-authored-by: Fernando Prado Cabrillo --- code/API_definitions/age-vefification.yaml | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index 6e76f18..febd96c 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -441,12 +441,13 @@ components: schema: $ref: "#/components/schemas/ErrorInfo" examples: - GENERIC_422_UNSUPPORTED_IDENTIFIER: - description: None of the provided identifiers is supported by the implementation + GENERIC_422_SERVICE_NOT_APPLICABLE: + description: Service is not available for the provided identifier value: status: 422 - code: UNSUPPORTED_IDENTIFIER - message: The identifier provided is not supported. + code: SERVICE_NOT_APPLICABLE + message: The service is not available for the provided identifier. + GENERIC_422_MISSING_IDENTIFIER: description: The identifier is not included in the request and the identifier information cannot be derived from the 3-legged access token value: From a38da8770a1ec3754100a58cd6bb5f33aa57145d Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Thu, 28 Nov 2024 16:02:50 +0100 Subject: [PATCH 35/44] Update code/API_definitions/age-vefification.yaml Co-authored-by: Fernando Prado Cabrillo --- code/API_definitions/age-vefification.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index febd96c..943a5b5 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -260,7 +260,7 @@ components: ageCheck: type: "string" - description: Indicate 'true' when the age of the user is the same age or older than the age threshold (age >= age threshold), and 'false' if not (age < age threshold). Otherwise, 'not_available'. + description: Indicate `true` when the age of the user is the same age or older than the age threshold (age >= age threshold), and `false` if not (age < age threshold). If the Operator doesn't have enough information to perform the validation, a `not_available` can be returned. enum: - 'true' - 'false' From bb7e9337139f695347150af42957f1961dca24d8 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Thu, 28 Nov 2024 16:54:40 +0100 Subject: [PATCH 36/44] Update age-vefification.yaml --- code/API_definitions/age-vefification.yaml | 57 ++++++---------------- 1 file changed, 14 insertions(+), 43 deletions(-) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index 943a5b5..ae94e92 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -46,7 +46,7 @@ info: If the API call contain a formatting or other error, a `400 INVALID_ARGUMENT` error is returned. - If the network subscription cannot be identified from the provided parameters (e.g. the subscription identifier is not associated with any customer of the CSP), a `404 DEVICE_NOT_FOUND` error is returned. + If the network subscription cannot be identified from the provided parameters (e.g. the subscription identifier is not associated with any customer of the CSP), a `404 IDENTIFIER_NOT_FOUND` error is returned. If the API consumer has a valid access token but is not authorised to obtain tenure information for the specified network subscription, then a `403 PERMISSION_DENIED` error is returned. @@ -65,7 +65,7 @@ info: ### Error handling for unidentifiable devices: - - If the `phoneNumber` cannot be derived from the 3-legged access token, the server will return a `422 UNIDENTIFIABLE_DEVICE` error. + - If the `phoneNumber` cannot be derived from the 3-legged access token, the server will return a `422 MISSING_IDENTIFIER` error. ### Restrictions for tokens without an associated authenticated identifier: @@ -160,8 +160,6 @@ paths: $ref: '#/components/responses/Generic403' "404": $ref: '#/components/responses/Generic404' - "406": - $ref: '#/components/responses/Generic406' "415": $ref: '#/components/responses/Generic415' "422": @@ -295,9 +293,7 @@ components: Generic400: description: |- Problem with the client request. - In addition to regular scenario of `INVALID_ARGUMENT`, another scenario may exist. - - Indicated param combination is invalid (`"code": "KNOW_YOUR_CUSTOMER.INVALID_PARAM_COMBINATION","message": "Indicated parameter combination is invalid"`) headers: x-correlator: $ref: '#/components/headers/x-correlator' @@ -315,12 +311,6 @@ components: code: INVALID_ARGUMENT message: Client specified an invalid argument, request body or query param. - InvalidParamCombination: - value: - status: 400 - code: KNOW_YOUR_CUSTOMER.INVALID_PARAM_COMBINATION - message: Indicated parameter combination is invalid - Generic401: description: Authentication problem with the client request. Unauthorized error. Access Token related errors. headers: @@ -345,13 +335,9 @@ components: code: AUTHENTICATION_REQUIRED message: New authentication is required. - Generic403: description: | Client does not have sufficient permission. - In addition to regular scenario of `PERMISSION_DENIED`, another scenarios may exist: - - - Phone number cannot be deducted from access token context.(`{"code": "KNOW_YOUR_CUSTOMER.INVALID_TOKEN_CONTEXT","message": "Phone number mismatch with access token context"}`) headers: x-correlator: @@ -369,13 +355,6 @@ components: status: 403 code: PERMISSION_DENIED message: Client does not have sufficient permissions to perform this action. - GENERIC_403_INVALID_TOKEN_CONTEXT: - description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token - value: - status: 403 - code: INVALID_TOKEN_CONTEXT - message: "phoneNumber is not consistent with access token." - Generic404: description: | @@ -395,25 +374,13 @@ components: status: 404 code: NOT_FOUND message: The specified resource is not found. - - - Generic406: - description: Not Acceptable - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorInfo" - examples: - GENERIC_406_NOT_ACCEPTABLE: - description: API Server does not accept the media type (`Accept-*` header) indicated by API client + GENERIC_404_IDENTIFIER_NOT_FOUND: + description: Device identifier not found value: - status: 406 - code: NOT_ACCEPTABLE - message: The server cannot produce a response matching the content requested by the client through `Accept-*` headers. - + status: 404 + code: IDENTIFIER_NOT_FOUND + message: Device identifier not found. + Generic415: description: Unsupported Media Type headers: @@ -447,14 +414,18 @@ components: status: 422 code: SERVICE_NOT_APPLICABLE message: The service is not available for the provided identifier. - GENERIC_422_MISSING_IDENTIFIER: description: The identifier is not included in the request and the identifier information cannot be derived from the 3-legged access token value: status: 422 code: MISSING_IDENTIFIER message: The phone number cannot be identified. - + GENERIC_422_UNNECESSARY_IDENTIFIER: + description: An explicit identifier is provided when an API subject has already been identified from the access token + value: + status: 422 + code: UNNECESSARY_IDENTIFIER + message: The device is already identified by the access token. Generic429: description: Too Many Requests From b38239251748f56c736080d1225cc58bbdd239c5 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Fri, 29 Nov 2024 08:46:15 +0100 Subject: [PATCH 37/44] Update age-vefification.yaml --- code/API_definitions/age-vefification.yaml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-vefification.yaml index ae94e92..e9f74eb 100644 --- a/code/API_definitions/age-vefification.yaml +++ b/code/API_definitions/age-vefification.yaml @@ -310,6 +310,12 @@ components: status: 400 code: INVALID_ARGUMENT message: Client specified an invalid argument, request body or query param. + GENERIC_400_OUT_OF_RANGE: + description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested + value: + status: 400 + code: OUT_OF_RANGE + message: Client specified an invalid range. Generic401: description: Authentication problem with the client request. Unauthorized error. Access Token related errors. From cb50467aec5c15ebf14f50aab1cd983f0e363002 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Fri, 29 Nov 2024 14:46:43 +0100 Subject: [PATCH 38/44] Update and rename age-vefification.yaml to age-verification.yaml --- .../{age-vefification.yaml => age-verification.yaml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename code/API_definitions/{age-vefification.yaml => age-verification.yaml} (100%) diff --git a/code/API_definitions/age-vefification.yaml b/code/API_definitions/age-verification.yaml similarity index 100% rename from code/API_definitions/age-vefification.yaml rename to code/API_definitions/age-verification.yaml From 42b9298a0b8a3030d800579872e203af790d5030 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Mon, 2 Dec 2024 14:59:14 +0100 Subject: [PATCH 39/44] Update age-verification.yaml following Commonalities for errors handling --- code/API_definitions/age-verification.yaml | 21 ++++++++------------- 1 file changed, 8 insertions(+), 13 deletions(-) diff --git a/code/API_definitions/age-verification.yaml b/code/API_definitions/age-verification.yaml index e9f74eb..98f2f28 100644 --- a/code/API_definitions/age-verification.yaml +++ b/code/API_definitions/age-verification.yaml @@ -52,24 +52,19 @@ info: Other errors may be returned as specified below. - # Identifying a device from the access token + # Identifying the phone number from the access token - This specification defines the `phoneNumber` field as optional in API requests, specifically in cases where the API is accessed using a 3-legged access token, and the device can be uniquely identified by the token. This approach simplifies API usage for API consumers by relying on the device information associated with the access token used to invoke the API. + This API requires the API consumer to identify a phone number as the subject of the API as follows: + - When the API is invoked using a two-legged access token, the subject will be identified from the optional `phoneNumber` field, which therefore MUST be provided. + - When a three-legged access token is used however, this optional identifier MUST NOT be provided, as the subject will be uniquely identified from the access token. - ## Handling of device information: + This approach simplifies API usage for API consumers using a three-legged access token to invoke the API by relying on the information that is associated with the access token and was identified during the authentication process. - ### Optional phoneNumber for 3-legged tokens: + ## Error handling: - - When using a 3-legged access token, the device associated with the access token must be considered as the device for the API request. This means that the phoneNumber is not required in the request, and if included it must be neglected to simplify the API usage and avoid additional validations. + - If the subject cannot be identified from the access token and the optional `phoneNumber` field is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code. - - ### Error handling for unidentifiable devices: - - - If the `phoneNumber` cannot be derived from the 3-legged access token, the server will return a `422 MISSING_IDENTIFIER` error. - - ### Restrictions for tokens without an associated authenticated identifier: - - - For scenarios which do not have a single device identifier associated to the token during the authentication flow, e.g. 2-legged access tokens, the `phoneNumber` parameter MUST be provided in the API request. This ensures that the device identification is explicit and valid for each API call made with these tokens. + - If the subject can be identified from the access token and the optional `phoneNumber` field is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same phone number is identified by these two methods, as the server is unable to make this comparison. # Further info and support From f9ed8772c5c3fb2015f0b0b5349f52b29a9fd595 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Thu, 5 Dec 2024 14:25:49 +0100 Subject: [PATCH 40/44] Update code/API_definitions/age-verification.yaml Thanks Co-authored-by: Fernando Prado Cabrillo --- code/API_definitions/age-verification.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/code/API_definitions/age-verification.yaml b/code/API_definitions/age-verification.yaml index 98f2f28..c86cde5 100644 --- a/code/API_definitions/age-verification.yaml +++ b/code/API_definitions/age-verification.yaml @@ -237,6 +237,8 @@ components: birthdate: type: string + format: date + description: The birthdate of the customer, in ISO 8601 calendar date format (YYYY-MM-DD). email: From a9a9787c6ee52d7558c1f60f0707ddd78988e3b0 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Thu, 5 Dec 2024 14:26:34 +0100 Subject: [PATCH 41/44] Update code/API_definitions/age-verification.yaml Co-authored-by: Fernando Prado Cabrillo --- code/API_definitions/age-verification.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/code/API_definitions/age-verification.yaml b/code/API_definitions/age-verification.yaml index c86cde5..d2aa8ad 100644 --- a/code/API_definitions/age-verification.yaml +++ b/code/API_definitions/age-verification.yaml @@ -243,6 +243,8 @@ components: email: type: string + format: email + description: Email address of the customer in the RFC specified format (local-part@domain). From e60ddc37474a809c2ae0dd92b3c441d7debd4212 Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Tue, 10 Dec 2024 12:19:01 +0100 Subject: [PATCH 42/44] Update code/API_definitions/age-verification.yaml Co-authored-by: Fernando Prado Cabrillo --- code/API_definitions/age-verification.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/code/API_definitions/age-verification.yaml b/code/API_definitions/age-verification.yaml index d2aa8ad..a1adf7b 100644 --- a/code/API_definitions/age-verification.yaml +++ b/code/API_definitions/age-verification.yaml @@ -30,7 +30,8 @@ info: The endpoint request body is a JSON object with the following parameters: - `phoneNumber`: The network subscription identifier (i.e. the phone number of the subscriber). [Required only in case a 2-legged flow has been agreed between API Provider and API Consumer; otherwise, none] - `ageThreshold`: The date's threshold from which the age of the user must be compared. [Required] - - any of `idDocument`, `name`, `givenName`, `familyName`, `middieNames`, `familyNameAtBirth`, `birthdate`, `email`; user's information to be checked in order to confirm that the user is the contract's owner [Optional] + - any of `idDocument`, `name`, `givenName`, `familyName`, `middleNames`, `familyNameAtBirth`, `birthdate`, `email`; user's information to be checked in order to confirm that the user is the contract's owner [Optional] + ## Outputs From a0dd2092df270506023bffa7e03ae8ba494af51f Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Tue, 10 Dec 2024 12:19:09 +0100 Subject: [PATCH 43/44] Update code/API_definitions/age-verification.yaml Co-authored-by: Fernando Prado Cabrillo --- code/API_definitions/age-verification.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/code/API_definitions/age-verification.yaml b/code/API_definitions/age-verification.yaml index a1adf7b..f94b5c6 100644 --- a/code/API_definitions/age-verification.yaml +++ b/code/API_definitions/age-verification.yaml @@ -103,7 +103,8 @@ paths: security: - openId: - - kyc-ageverify:ageVerify + - kyc-ageverify:ageverify + parameters: From 22359e3aa3cd1fd686d15245bdd52553fac203ff Mon Sep 17 00:00:00 2001 From: Gilles Renoux <144710412+GillesInnov35@users.noreply.github.com> Date: Tue, 10 Dec 2024 14:38:59 +0100 Subject: [PATCH 44/44] Update code/API_definitions/age-verification.yaml Thanks Fernando Co-authored-by: Fernando Prado Cabrillo --- code/API_definitions/age-verification.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/code/API_definitions/age-verification.yaml b/code/API_definitions/age-verification.yaml index f94b5c6..cf7685a 100644 --- a/code/API_definitions/age-verification.yaml +++ b/code/API_definitions/age-verification.yaml @@ -271,8 +271,11 @@ components: identityMatchScore: type: "integer" + minimum: 0 + maximum: 100 description: An aggregate match score of user's identity when available in the request body. + ErrorInfo: type: "object" required: