Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Initial API proposal (for merging proposed YAML of PR#9) #10

Merged
merged 16 commits into from
Nov 12, 2024
Merged
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
285 changes: 285 additions & 0 deletions code/API_definitions/number-recycling.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,285 @@
openapi: 3.0.3
info:
title: Number Recycling
description: |
The API can be used to check whether the subscriber of the phone number has changed.
A common scenario is when a fraudster obtains a phone number that previously belonged to another person who did not properly deactivate or verify it. The fraudster can then use this number to commit identity theft or engage in fraudulent activities, such as obtaining access codes for accounts associated with that number. In some cases, fraudsters may also attempt to use services or avoid charges by leveraging old, no longer used numbers that were previously used by other users.
Response includes whether there will be changes from the specified date.

### 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.

# Identifying a 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 phone number can be uniquely identified by the token. This approach simplifies API usage for API consumers by relying on the information associated with the access token used to invoke the API.

## Handling of phone number information:

### Optional `phoneNumber` field for 3-legged tokens:

- When using a 3-legged access token, the phone number associated with the access token must be considered as the phone number for the API request. This means that the `phoneNumber` field is not required in the request, and if included it must identify the same phone number, 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 phone number identification from the access token, if available.
- If the API request additionally includes a `phoneNumber` field when using a 3-legged access token, the API will validate that the phone number 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 phone number information in the request does not match the token.

### Error handling for unidentifiable phone number:

- If the `phoneNumber` field is not included in the request and the phone number information cannot be derived from the 3-legged access token, the server will return a 422 `UNIDENTIFIABLE_PHONE_NUMBER` error.

### Restrictions for tokens without an associated authenticated phone number:

For scenarios which do not have a phone number associated to the token during the authentication flow, e.g. 2-legged access tokens, the `phoneNumber` field MUST be provided in the API request. This ensures that the phone number is explicit and valid for each API call made with these tokens.

version: wip
x-camara-commonalities: 0.4.0
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
externalDocs:
description: Product documentation at Camara
url: https://github.com/camaraproject/NumberRecycling
servers:
- url: '{apiRoot}/number-recycling/vwip'
variables:
apiRoot:
default: http://localhost:9091
description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`
paths:
/check:
post:
security:
- openId:
- number-recycling:check
tags:
- Check Number Recycling
description: Check whether the subscriber of the phone number has changed.
operationId: checkNumberRecycling
parameters:
- $ref: '#/components/parameters/x-correlator'
requestBody:
description: |
Check whether the subscriber of the phone number has changed.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCheckNumRecycling'
required: true
responses:
'200':
$ref: '#/components/responses/Generic200'
'400':
$ref: '#/components/responses/Generic400'
'401':
$ref: '#/components/responses/Generic401'
'403':
$ref: '#/components/responses/Generic403'
'404':
$ref: '#/components/responses/Generic404'
'422':
$ref: '#/components/responses/Generic422'
'500':
$ref: '#/components/responses/Generic500'
'503':
$ref: '#/components/responses/Generic503'
components:
securitySchemes:
openId:
type: openIdConnect
openIdConnectUrl: https://example.com/.well-known/openid-configuration
parameters:
x-correlator:
name: x-correlator
in: header
description: Correlation id for the different services
schema:
type: string
headers:
x-correlator:
description: Correlation id for the different services
schema:
type: string
schemas:
CreateCheckNumRecycling:
type: object
oneOf:
- required: [specifiedDateTime]
- required: [specifiedDate]
properties:
phoneNumber:
$ref: '#/components/schemas/PhoneNumber'
specifiedDateTime:
type: string
format: date-time
description: Specified date to check whether there has been a change in the subscriber associated with the specific phone number. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z)
specifiedDate:
type: string
description: Specified date to check whether there has been a change in the subscriber associated with the specific phone number, in ISO 8601 calendar date format (YYYY-MM-DD).
yamamoto0104 marked this conversation as resolved.
Show resolved Hide resolved
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"
CheckNumRecyclingInfo:
type: object
required:
- phoneNumChanged
properties:
phoneNumChanged:
type: boolean
description: |
Set to true (Boolean, not string) when there has been a change in the subscriber associated with the specific phone number after “specifiedDate”.
ErrorInfo:
type: object
required:
- status
- code
- detail
properties:
status:
type: integer
description: HTTP response status code
code:
type: string
description: Code given to this error
detail:
type: string
description: Detailed error description
responses:
Generic200:
description: OK
headers:
x-correlator:
description: Correlation id for the different services
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/CheckNumRecyclingInfo'
Generic400:
description: Problem with the client request
headers:
x-correlator:
description: Correlation id for the different services
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
example:
status: 400
code: INVALID_ARGUMENT
detail: Client specified an invalid argument, request body or query param
Generic401:
description: Authentication problem with the client request
headers:
x-correlator:
description: Correlation id for the different services
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
example:
status: 401
code: UNAUTHENTICATED
detail: Request not authenticated due to missing, invalid, or expired credentials
Generic403:
description: Client does not have sufficient permission
headers:
x-correlator:
description: Correlation id for the different services
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
examples:
PermissionDenied:
value:
status: 403
code: PERMISSION_DENIED
detail: Client does not have sufficient permissions to perform this action
InvalidTokenContext:
value:
status: 403
code: INVALID_TOKEN_CONTEXT
detail: Phone number cannot be deducted from access token context
Generic404:
description: Resource Not Found
headers:
x-correlator:
description: Correlation id for the different services
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
example:
status: 404
code: NOT_FOUND
detail: A specified resource is not found
Generic422:
description: Unprocessable Content
headers:
x-correlator:
description: Correlation id for the different services
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
examples:
NotSupported:
value:
status: 422
code: NOT_SUPPORTED
detail: Service not supported for this phoneNumber
UnidentifiablePhoneMumber:
value:
status: 422
code: UNIDENTIFIABLE_PHONE_NUMBER
detail: The phone number cannot be identified
Generic500:
description: Server error
headers:
x-correlator:
description: Correlation id for the different services
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
example:
status: 500
code: INTERNAL
detail: Server error
Generic503:
description: Service unavailable. Typically the server is down.
headers:
x-correlator:
description: Correlation id for the different services
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
example:
status: 503
code: UNAVAILABLE
detail: Service unavailable