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

Update error codes and description to align with Commonalities #13

Merged
merged 7 commits into from
Nov 28, 2024
Merged
Changes from all 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
66 changes: 28 additions & 38 deletions code/API_definitions/number-recycling.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -50,29 +50,19 @@ info:

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
# 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 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.
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 phone number 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` field for 3-legged tokens:
## Error handling:

- 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.
- 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_PHONE_NUMBER` error code.
- 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_PHONE_NUMBER` error code. This will the case even if the same phone number is identified by these two methods, as the server is unable to make this comparison.

### 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
Expand Down Expand Up @@ -174,17 +164,17 @@ components:
required:
- status
- code
- detail
- message
properties:
status:
type: integer
description: HTTP response status code
code:
type: string
description: Code given to this error
detail:
message:
type: string
description: Detailed error description
description: A human readable description of what the event represent
responses:
Generic200:
description: OK
Expand All @@ -211,7 +201,7 @@ components:
example:
status: 400
code: INVALID_ARGUMENT
detail: Client specified an invalid argument, request body or query param
message: Request body does not comply with the schema
Generic401:
description: Authentication problem with the client request
headers:
Expand All @@ -226,7 +216,7 @@ components:
example:
status: 401
code: UNAUTHENTICATED
detail: Request not authenticated due to missing, invalid, or expired credentials
message: Request not authenticated due to missing, invalid, or expired credentials
Generic403:
description: Client does not have sufficient permission
headers:
Expand All @@ -243,12 +233,7 @@ components:
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
message: Client does not have sufficient permissions to perform this action
Generic404:
description: Resource Not Found
headers:
Expand All @@ -263,7 +248,7 @@ components:
example:
status: 404
code: NOT_FOUND
detail: A specified resource is not found
message: A specified resource is not found
Generic422:
description: Unprocessable Content
headers:
Expand All @@ -276,16 +261,21 @@ components:
schema:
$ref: '#/components/schemas/ErrorInfo'
examples:
NotSupported:
DeviceNotApplicable:
value:
status: 422
code: DEVICE_NOT_APPLICABLE
message: The service is not available for the provided phone number
UnnecessaryIdentifier:
value:
status: 422
code: NOT_SUPPORTED
detail: Service not supported for this phoneNumber
UnidentifiablePhoneMumber:
code: UNNECESSARY_IDENTIFIER
message: The phone number is already identified by the access token
MissingIdentifier:
value:
status: 422
code: UNIDENTIFIABLE_PHONE_NUMBER
detail: The phone number cannot be identified
code: MISSING_IDENTIFIER
message: The phone number cannot be identified
Generic500:
description: Server error
headers:
Expand All @@ -300,7 +290,7 @@ components:
example:
status: 500
code: INTERNAL
detail: Server error
message: Unknown server error. Typically a server bug.
Generic503:
description: Service unavailable. Typically the server is down.
headers:
Expand All @@ -315,4 +305,4 @@ components:
example:
status: 503
code: UNAVAILABLE
detail: Service unavailable
message: Service unavailable