diff --git a/code/API_definitions/number_verification.yaml b/code/API_definitions/number_verification.yaml
index 0a881b1..4903f05 100644
--- a/code/API_definitions/number_verification.yaml
+++ b/code/API_definitions/number_verification.yaml
@@ -40,7 +40,9 @@ info:
# Authorization and authentication
- CAMARA guidelines defines a set of authorization flows which can grant API clients access to the API functionality, as outlined in the document [CAMARA-API-access-and-user-consent.md](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md). 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.
+ 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.
@@ -164,6 +166,11 @@ components:
openId:
type: openIdConnect
openIdConnectUrl: https://example.com/.well-known/openid-configuration
+ headers:
+ x-correlator:
+ description: Correlation id for the different services
+ schema:
+ type: string
schemas:
NumberVerificationRequestBody:
type: object
@@ -224,10 +231,8 @@ components:
Generic400:
description: Problem with the client request
headers:
- X-Correlator:
- description: Correlation id for the different services
- schema:
- type: string
+ x-correlator:
+ $ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
@@ -237,20 +242,27 @@ components:
code: INVALID_ARGUMENT
message: Client specified an invalid argument, request body or query param
Generic401:
- description: Authentication problem with the client request
+ description: Unauthorized
headers:
- X-Correlator:
- description: Correlation id for the different services
- schema:
- type: string
+ x-correlator:
+ $ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
- example:
- status: 401
- code: UNAUTHENTICATED
- message: Request not authenticated due to missing, invalid, or expired credentials
+ examples:
+ GENERIC_401_UNAUTHENTICATED:
+ description: Request cannot be authenticated
+ 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.
PhoneNumberVerificationPermissionDenied403:
description: |
Client does not have sufficient permission.
@@ -258,37 +270,34 @@ components:
- Client authentication was not via mobile network. In order to check the authentication method, AMR parameter value in the 3-legged user's access token can be used and make sure that the authentication was not either by SMS+OTP nor username/password (`{"code": "NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK","message": "Client must authenticate via the mobile network to use this service"}`)
- Phone number cannot be deducted from access token context.(`{"code": "NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT","message": "Phone number cannot be deducted from access token context"}`)
headers:
- X-Correlator:
- description: Correlation id for the different services
- schema:
- type: string
+ x-correlator:
+ $ref: "#/components/headers/x-correlator"
content:
application/json:
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
- UserNotAuthenticatedByMobileNetwork:
+ message: Client does not have sufficient permissions to perform this action.
+ GENERIC_403_USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK:
value:
status: 403
code: NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK
message: Client must authenticate via the mobile network to use this service
- InvalidTokenContext:
+ GENERIC_403_INVALID_TOKEN_CONTEXT:
value:
status: 403
- code: NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT
+ code: INVALID_TOKEN_CONTEXT
message: Phone number cannot be deducted from access token context
Generic500:
description: Server error
headers:
- X-Correlator:
- description: Correlation id for the different services
- schema:
- type: string
+ x-correlator:
+ $ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
@@ -300,10 +309,8 @@ components:
Generic503:
description: Service unavailable. Typically the server is down.
headers:
- X-Correlator:
- description: Correlation id for the different services
- schema:
- type: string
+ x-correlator:
+ $ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
@@ -315,10 +322,8 @@ components:
Generic504:
description: Request time exceeded. If it happens repeatedly, consider reducing the request complexity
headers:
- X-Correlator:
- description: Correlation id for the different services
- schema:
- type: string
+ x-correlator:
+ $ref: "#/components/headers/x-correlator"
content:
application/json:
schema:
diff --git a/documentation/API_documentation/NumberVerification_verify_User_Story.md b/documentation/API_documentation/NumberVerification_verify_User_Story.md
new file mode 100644
index 0000000..d058ec3
--- /dev/null
+++ b/documentation/API_documentation/NumberVerification_verify_User_Story.md
@@ -0,0 +1,10 @@
+# Number Verification Verify API User Story
+
+| **Item** | **Details** |
+| ---- | ------- |
+| ***Summary*** | As an enterprise application developer, I want to verify the phone number associated with the phone from which the call was made, so I can get a proof of possession of the phone number. |
+| ***Roles, Actors and Scope*** | **Roles:** Customer:User, Customer:BusinessManager, Customer:Administrator
, end-user, Communication Service Provider (CSP), Channel Partner **Actors:** Application service providers, hyperscalers, aggregator, application developers, end users, Communication Service Provider (CSP).
**Scope:**
- Verifies if the specified phone number (plain text or hashed format) matches the one that the user is currently using. |
+| ***Pre-conditions*** |The preconditions are listed below: