diff --git a/code/API_definitions/CAMARA/number_verification.yaml b/code/API_definitions/CAMARA/number_verification.yaml index d7012f3..b64515f 100644 --- a/code/API_definitions/CAMARA/number_verification.yaml +++ b/code/API_definitions/CAMARA/number_verification.yaml @@ -14,7 +14,7 @@ info: This API currently provides two endpoints where both require a **3-legged token** and authentication via **mobile network** (excluding for example by SMS/OTP or user/password as an authentication method): - The first one checks if the user mobile phone number matches the phone number associated with the mobile device. It can receive either a hashed or a plain text phone number as input and it compares the received input with the authenticated user's phone number associated to the access token in order to respond **true/false**. - The next one retrieves the phone number associated to the user's token and returns it so the verification can be made by the service provider. - version: 0.2.0 + version: 0.3.0 termsOfService: http://example.com/terms/ contact: name: API Support @@ -74,17 +74,17 @@ paths: schema: $ref: '#/components/schemas/NumberVerificationMatchResponse' '400': - $ref: '#/components/responses/InvalidArgument' + $ref: '#/components/responses/Generic400' '401': - $ref: '#/components/responses/Unauthenticated' + $ref: '#/components/responses/Generic401' '403': - $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied' + $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied403' '500': - $ref: '#/components/responses/Internal' + $ref: '#/components/responses/Generic500' '503': - $ref: '#/components/responses/Unavailable' + $ref: '#/components/responses/Generic503' '504': - $ref: '#/components/responses/Timeout' + $ref: '#/components/responses/Generic504' security: - three_legged: - number-verification-verify-read @@ -118,17 +118,17 @@ paths: schema: $ref: '#/components/schemas/NumberVerificationShareResponse' '400': - $ref: '#/components/responses/InvalidArgument' + $ref: '#/components/responses/Generic400' '401': - $ref: '#/components/responses/Unauthenticated' + $ref: '#/components/responses/Generic401' '403': - $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied' + $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied403' '500': - $ref: '#/components/responses/Internal' + $ref: '#/components/responses/Generic500' '503': - $ref: '#/components/responses/Unavailable' + $ref: '#/components/responses/Generic503' '504': - $ref: '#/components/responses/Timeout' + $ref: '#/components/responses/Generic504' security: - three_legged: - number-verification-share-read @@ -147,14 +147,14 @@ components: PhoneNumber: type: object properties: - phone_number: + phoneNumber: description: A phone number belonging to the user. 'E164 with +' format type: string example: '+346661113334' HashedPhoneNumber: type: object properties: - hashed_phone_number: + hashedPhoneNumber: description: Hashed phone number. SHA-256 (in hexadecimal representation) of the mobile phone number in 'E164 with +' format type: string example: 32f67ab4e4312618b09cd23ed8ce41b13e095fe52b73b2e8da8ef49830e50dba @@ -162,17 +162,17 @@ components: type: object description: Number verification result required: - - device_phone_number_verified + - devicePhoneNumberVerified properties: - device_phone_number_verified: + devicePhoneNumberVerified: $ref: '#/components/schemas/DevicePhoneNumberVerified' NumberVerificationShareResponse: type: object description: Number verification share result required: - - device_phone_number + - devicePhoneNumber properties: - device_phone_number: + devicePhoneNumber: $ref: '#/components/schemas/DevicePhoneNumber' DevicePhoneNumber: description: The device phone number associated to the access token. 'E164 with +' format @@ -181,37 +181,24 @@ components: DevicePhoneNumberVerified: description: Number verification. True, if it matches type: boolean - ModelError: + ErrorInfo: type: object required: - status + - code - message properties: status: type: integer - minimum: 400 - maximum: 599 description: HTTP response status code + code: + type: string + description: Code given to this error message: type: string - description: A human readable description of what the event represent - PhoneNumberVerificationPermissionDenied: - allOf: - - type: object - required: - - code - properties: - code: - type: string - enum: - - PERMISSION_DENIED - - NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK - - NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT - default: PERMISSION_DENIED - description: Client does not have sufficient permissions to perform this action. - - $ref: '#/components/schemas/ModelError' + description: Detailed error description responses: - InvalidArgument: + Generic400: description: Problem with the client request headers: x-correlator: @@ -221,25 +208,12 @@ components: content: application/json: schema: - allOf: - - type: object - required: - - code - properties: - code: - type: string - enum: - - INVALID_ARGUMENT - default: INVALID_ARGUMENT - description: Client specified an invalid argument, request body or query param. - - $ref: '#/components/schemas/ModelError' - examples: - response: - value: - status: 400 - code: INVALID_ARGUMENT - message: Client specified an invalid argument, request body or query param - Unauthenticated: + $ref: '#/components/schemas/ErrorInfo' + example: + status: 400 + code: INVALID_ARGUMENT + message: Client specified an invalid argument, request body or query param + Generic401: description: Authentication problem with the client request headers: x-correlator: @@ -249,25 +223,12 @@ components: content: application/json: schema: - allOf: - - type: object - required: - - code - properties: - code: - type: string - enum: - - UNAUTHENTICATED - default: UNAUTHENTICATED - description: Request not authenticated due to missing, invalid, or expired credentials. - - $ref: '#/components/schemas/ModelError' - examples: - response: - value: - status: 401 - code: UNAUTHENTICATED - message: Request not authenticated due to missing, invalid, or expired credentials - PhoneNumberVerificationPermissionDenied: + $ref: '#/components/schemas/ErrorInfo' + example: + status: 401 + code: UNAUTHENTICATED + message: Request not authenticated due to missing, invalid, or expired credentials + PhoneNumberVerificationPermissionDenied403: description: |- Client does not have sufficient permission. In addition to regular scenario of `PERMISSION_DENIED`, other scenarios may exist: @@ -281,14 +242,24 @@ components: content: application/json: schema: - $ref: '#/components/schemas/PhoneNumberVerificationPermissionDenied' + $ref: '#/components/schemas/ErrorInfo' examples: - response: + PermissionDenied: + value: + status: 403 + code: PERMISSION_DENIED + message: Client does not have sufficient permissions to perform this action + UserNotAuthenticatedByMobileNetwork: value: status: 403 code: NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK message: Client must authenticate via the mobile network to use this service - Internal: + InvalidTokenContext: + value: + status: 403 + code: HOME_DEVICES_QOD.INVALID_TOKEN_CONTEXT + message: Phone number cannot be deducted from access token context + Generic500: description: Server error headers: x-correlator: @@ -298,25 +269,12 @@ components: content: application/json: schema: - allOf: - - type: object - required: - - code - properties: - code: - type: string - enum: - - INTERNAL - default: INTERNAL - description: Unknown server error.Typically a server bug. - - $ref: '#/components/schemas/ModelError' - examples: - response: - value: - status: 500 - code: INTERNAL - message: Server error - Unavailable: + $ref: '#/components/schemas/ErrorInfo' + example: + status: 500 + code: INTERNAL + message: Server error + Generic503: description: Service unavailable. Typically the server is down. headers: x-correlator: @@ -326,25 +284,12 @@ components: content: application/json: schema: - allOf: - - type: object - required: - - code - properties: - code: - type: string - enum: - - UNAVAILABLE - default: UNAVAILABLE - description: Request timeout exceeded - - $ref: '#/components/schemas/ModelError' - examples: - response: - value: - status: 503 - code: UNAVAILABLE - message: Service unavailable - Timeout: + $ref: '#/components/schemas/ErrorInfo' + example: + status: 503 + code: UNAVAILABLE + message: Service unavailable + Generic504: description: Request time exceeded. If it happens repeatedly, consider reducing the request complexity headers: x-correlator: @@ -354,24 +299,11 @@ components: content: application/json: schema: - allOf: - - type: object - required: - - code - properties: - code: - type: string - enum: - - TIMEOUT - default: TIMEOUT - description: Request timeout exceeded - - $ref: '#/components/schemas/ModelError' - examples: - response: - value: - status: 504 - code: TIMEOUT - message: Request timeout exceeded. Try later. + $ref: '#/components/schemas/ErrorInfo' + example: + status: 504 + code: TIMEOUT + message: Request timeout exceeded. Try later. externalDocs: description: Project documentation at CAMARA url: https://github.com/camaraproject/NumberVerification diff --git a/documentation/API_documentation/CAMARA/NUMBER_VERIFICATION_API.md b/documentation/API_documentation/CAMARA/NUMBER_VERIFICATION_API.md index ae25ae8..867cffc 100644 --- a/documentation/API_documentation/CAMARA/NUMBER_VERIFICATION_API.md +++ b/documentation/API_documentation/CAMARA/NUMBER_VERIFICATION_API.md @@ -59,9 +59,9 @@ Following table defines API endpoints of exposed REST based for Number Verificat | **Request to verify a number** | | -------------------------- | -| **HTTP Request**
POST /number-verification/v0/verify
**Query Parameters**
No query parameters are defined.
**Path Parameters**
No path parameters are defined.
**Request Body Parameters**
**One of:**
**phone_number**: A phone number belonging to the user. 'E164 with +' format.
**hashed_phone_number**: Hashed phone number. SHA-256 (in hexadecimal representation) of the mobile phone number in 'E164 with +' format. +| **HTTP Request**
POST /number-verification/v0/verify
**Query Parameters**
No query parameters are defined.
**Path Parameters**
No path parameters are defined.
**Request Body Parameters**
**One of:**
**phoneNumber**: A phone number belonging to the user. 'E164 with +' format.
**hashedPhoneNumber**: Hashed phone number. SHA-256 (in hexadecimal representation) of the mobile phone number in 'E164 with +' format. -
**Response**
**200: OK**
Response body:
**device_phone_number_verified** : Boolean
**400:** **INVALID_ARGUMENT**
**401:** **UNAUTHENTICATED**
**403:** **PERMISSION_DENIED**
**403:** **NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK**
**403:** **NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT**
**500:** **INTERNAL**
**503:** **UNAVAILABLE**
**504:** **TIMEOUT**
+
**Response**
**200: OK**
Response body:
**devicePhoneNumberVerified** : Boolean
**400:** **INVALID_ARGUMENT**
**401:** **UNAUTHENTICATED**
**403:** **PERMISSION_DENIED**
**403:** **NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK**
**403:** **NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT**
**500:** **INTERNAL**
**503:** **UNAVAILABLE**
**504:** **TIMEOUT**


@@ -70,7 +70,7 @@ Following table defines API endpoints of exposed REST based for Number Verificat | -------------------------- | | **HTTP Request**
GET /number-verification/v0/device-phone-number
**Query Parameters**
No query parameters are defined.
**Path Parameters**
No path parameters are defined.
**Request Body Parameters**
No body -
**Response**
**200: OK**
Response body:
**device_phone_number** : The device phone number associated to the access token. 'E164 with +' format.
**400:** **INVALID_ARGUMENT**
**401:** **UNAUTHENTICATED**
**403:** **PERMISSION_DENIED**
**403:** **NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK**
**403:** **NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT**
**500:** **INTERNAL**
**503:** **UNAVAILABLE**
**504:** **TIMEOUT**
+
**Response**
**200: OK**
Response body:
**devicePhoneNumber** : The device phone number associated to the access token. 'E164 with +' format.
**400:** **INVALID_ARGUMENT**
**401:** **UNAUTHENTICATED**
**403:** **PERMISSION_DENIED**
**403:** **NUMBER_VERIFICATION.USER_NOT_AUTHENTICATED_BY_MOBILE_NETWORK**
**403:** **NUMBER_VERIFICATION.INVALID_TOKEN_CONTEXT**
**500:** **INTERNAL**
**503:** **UNAVAILABLE**
**504:** **TIMEOUT**


@@ -109,14 +109,14 @@ Please note, the credentials for API authentication purposes need to be adjusted | Snippet 1. Request code | | ----------------------------------------------- | -| curl -X 'POST' `https://sample-base-url/number-verification/v0/verify`
-H 'accept: application/json'
-H 'Content-Type: application/json'
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...."
-d '{ "hashed_phone_number": "32f67ab4e4312618b09cd23ed8ce41b13e095fe52b73b2e8da8ef49830e50dba"}' | -| The response will be:
200
-d '{ "device_phone_number_verified": true }'| +| curl -X 'POST' `https://sample-base-url/number-verification/v0/verify`
-H 'accept: application/json'
-H 'Content-Type: application/json'
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...."
-d '{ "hashedPhoneNumber": "32f67ab4e4312618b09cd23ed8ce41b13e095fe52b73b2e8da8ef49830e50dba"}' | +| The response will be:
200
-d '{ "devicePhoneNumberVerified": true }'|
| Snippet 2. Validate code | | ----------------------------------------------- | | curl -X 'GET' `https://sample-base-url/number-verification/v0/device-phone-number`
-H 'accept: application/json'
-H 'Content-Type: application/json'
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...."
| -| The response will be:
200
-d '{ "device_phone_number": "+346661113334" }'| +| The response will be:
200
-d '{ "devicePhoneNumber": "+346661113334" }'|