Skip to content

Commit

Permalink
Merge pull request #346 from eric-murray/eric-murray-patch-1
Browse files Browse the repository at this point in the history
Small typo fix to info.description template
  • Loading branch information
rartych authored Nov 28, 2024
2 parents a0cd134 + a22eb32 commit 69729f5
Showing 1 changed file with 2 additions and 2 deletions.
4 changes: 2 additions & 2 deletions documentation/API-design-guidelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
```

0 comments on commit 69729f5

Please sign in to comment.