openapi: 3.0.3 info: title: Global System for Mobile Communications GSMA Camara Project Number Verification description: >- Service Enabling Network Function API to verify that the provided **mobile phone number** is the one used in the device. It verifies that the user is using a device with the same *mobile phone number* as it is declared. It also makes it possible for a Service provider to verify the number itself by returning the phone number associated to the authenticated user's access token. version: 1.0.0 x-camara-commonalities: 0.4.0 license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: '{apiRoot}/number-verification/v1' variables: apiRoot: default: http://localhost:9091 description: >- API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath tags: - name: Phone Number Share description: API operation to return the phone number associated to the access token. - name: Phone Number Verify description: >- API operation to verify a phone number received as input. It can be received either in plain text or hashed format. paths: /verify: post: tags: - Phone Number Verify summary: >- Global System for Mobile Communications Verifies if the received hashed/plain text phone number matches the phone number associated with the access token description: > Verifies if the specified phone number (either in plain text or hashed format) matches the one that the user is currently using. Only one of the plain or hashed formats must be provided. - The number verification will be done for the user that has authenticated via mobile network - It returns true/false depending on if the hashed phone number received as input matches the authenticated user's `device phone number` associated to the access token operationId: phoneNumberVerify parameters: - in: header name: x-correlator required: false description: Correlation id for the different services schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/NumberVerificationRequestBody' required: true responses: '200': description: OK headers: x-correlator: description: Correlation id for the different services schema: type: string content: application/json: schema: $ref: '#/components/schemas/NumberVerificationMatchResponse' '400': $ref: '#/components/responses/Generic400' '401': $ref: '#/components/responses/Generic401' '403': $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied403' '500': $ref: '#/components/responses/Generic500' '503': $ref: '#/components/responses/Generic503' '504': $ref: '#/components/responses/Generic504' security: - openId: - number-verification:verify /device-phone-number: get: tags: - Phone Number Share summary: Global System for Mobile Communications Returns the phone number associated with the access token description: > Returns the phone number so the API clients can verify the number themselves: - It will be done for the user that has authenticated via mobile network - It returns the authenticated user's `device phone number` associated to the access token operationId: phoneNumberShare parameters: - in: header name: x-correlator required: false description: Correlation id for the different services schema: type: string responses: '200': description: OK headers: x-correlator: description: Correlation id for the different services schema: type: string content: application/json: schema: $ref: '#/components/schemas/NumberVerificationShareResponse' '400': $ref: '#/components/responses/Generic400' '401': $ref: '#/components/responses/Generic401' '403': $ref: '#/components/responses/PhoneNumberVerificationPermissionDenied403' '500': $ref: '#/components/responses/Generic500' '503': $ref: '#/components/responses/Generic503' '504': $ref: '#/components/responses/Generic504' security: - openId: - number-verification:device-phone-number:read 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 schemas: NumberVerificationRequestBody: type: object description: Payload to verify the phone number. minProperties: 1 maxProperties: 1 properties: phoneNumber: type: string pattern: ^\+[1-9][0-9]{4,14}$ example: '+123456789' 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 '+'. hashedPhoneNumber: description: >- Hashed phone number. SHA-256 (in hexadecimal representation) of the mobile phone number in **E.164 format (starting with country code)**. Prefixed with '+'. type: string example: 32f67ab4e4312618b09cd23ed8ce41b13e095fe52b73b2e8da8ef49830e50dba NumberVerificationMatchResponse: type: object description: Number verification result required: - devicePhoneNumberVerified properties: devicePhoneNumberVerified: $ref: '#/components/schemas/DevicePhoneNumberVerified' NumberVerificationShareResponse: type: object description: Number verification share result required: - devicePhoneNumber properties: devicePhoneNumber: $ref: '#/components/schemas/DevicePhoneNumber' DevicePhoneNumber: type: string pattern: ^\+[1-9][0-9]{4,14}$ example: '+123456789' 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 '+'. DevicePhoneNumberVerified: description: Number verification. True, if it matches type: boolean 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 headers: x-correlator: $ref: '#/components/headers/x-correlator' content: application/json: schema: $ref: '#/components/schemas/ErrorInfo' example: status: 400 code: INVALID_ARGUMENT message: Client specified an invalid argument, request body or query param Generic401: description: Unauthorized headers: x-correlator: $ref: '#/components/headers/x-correlator' content: application/json: schema: $ref: '#/components/schemas/ErrorInfo' 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. In addition to regular scenario of `PERMISSION_DENIED`, other scenarios may exist: - 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": "INVALID_TOKEN_CONTEXT","message": "Phone number cannot be deducted from access token context"}`) headers: x-correlator: $ref: '#/components/headers/x-correlator' content: application/json: schema: $ref: '#/components/schemas/ErrorInfo' examples: 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. 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 GENERIC_403_INVALID_TOKEN_CONTEXT: value: status: 403 code: INVALID_TOKEN_CONTEXT message: Phone number cannot be deducted from access token context Generic500: description: Server error headers: x-correlator: $ref: '#/components/headers/x-correlator' content: application/json: schema: $ref: '#/components/schemas/ErrorInfo' example: status: 500 code: INTERNAL message: Server error Generic503: description: Service unavailable. Typically the server is down. headers: x-correlator: $ref: '#/components/headers/x-correlator' content: application/json: schema: $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: $ref: '#/components/headers/x-correlator' content: application/json: schema: $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