From 9bbf7983357ccdf3c157aee8a34ea201833aa4a4 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Thu, 28 Nov 2024 14:30:27 +0000 Subject: [PATCH 1/2] Small typo fix --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 43cc2401..a14f3b3c 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -2084,5 +2084,5 @@ This approach simplifies API usage for API consumers using a three-legged access - If the subject cannot be identified from the access token and the optional [`device` object | `phoneNumber` field](*) is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code. -- If the subject can be identified from the access token and the optional [`device` object | `phoneNumber` field](*) is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will the case even if the same [ device | phone number ](*) is identified by these two methods, as the server is unable to make this comparison. +- If the subject can be identified from the access token and the optional [`device` object | `phoneNumber` field](*) is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same [ device | phone number ](*) is identified by these two methods, as the server is unable to make this comparison. ``` From a22eb32f4e15f5be3a7d171164be1491213392d9 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Thu, 28 Nov 2024 15:37:27 +0000 Subject: [PATCH 2/2] Update API-design-guidelines.md --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index a14f3b3c..54e98dfc 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -2049,7 +2049,7 @@ When an API requires a User (as defined by the [ICM Glossary](https://github.com - If the access token is a Three-Legged Access Token, then the User will already have been associated with that token by the API provider, which in turn may be identified from the physical device that calls the `/authorize` endpoint for the OIDC authorisation code flow, or from the `login_hint` parameter of the OIDC CIBA flow (which can be a device IP, phone number or operator token). The `sub` claim of the ID token returned with the access token will confirm that an association with the User has been made, although this will not identify the User directly given that the `sub` will not be a globally unique identifier nor contain PII as per the [CAMARA Security and Interoperability Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md#id-token-sub-claim) requirements. - If the access token is a Two-Legged Access Token, no User is associated with the token, an hence an explicit identifier MUST be provided. This is typically either a `Device` object named `device`, or a `PhoneNumber` string named `phoneNumber`. Both of these schema are defined in the [CAMARA_common.yaml](/artifacts/CAMARA_common.yaml) artifact. In both cases, it is the User that is being identified, although the `device` identifier allows this indirectly by identifying an active physical device. -If an API provider issues Thee-Legged Access Tokens for use with the API, the following error may occur: +If an API provider issues Three-Legged Access Tokens for use with the API, the following error may occur: - **Both a Three-Legged Access Token and an explicit User identifier (device or phone number) are provided by the API consumer.** Whilst it might be considered harmless to proceed if both identify the same User, returning an error only when the two do not match would allow the API consumer to confirm the identity of the User associated with the access token, which they might otherwise not know. Although this functionality is supported by some APIs (e.g. Number Verification, KYC Match), for others it may exceed the scope consented to by the User.