diff --git a/code/API_definitions/session-insights.yaml b/code/API_definitions/session-insights.yaml index 9a586a1..e21e47d 100644 --- a/code/API_definitions/session-insights.yaml +++ b/code/API_definitions/session-insights.yaml @@ -52,7 +52,11 @@ info: # Authorization and Authentication - The Session Insights API monitors network quality from an application running on a specific device. The API provider needs to know which device the session relates to, and this is determined by the type of access token used: + The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile. + + The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation. + + In cases where personal 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 three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design. ## Identifying the device from the access token @@ -65,7 +69,7 @@ info: - If the subject cannot be identified from the access token and the optional `device` object 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` 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. + - If the subject can be identified from the access token and the optional `device` 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 is identified by these two methods, as the server is unable to make this comparison. # Additional CAMARA error responses @@ -117,6 +121,9 @@ paths: The API provider allocates a sink (HTTP webhook or MQTT topic) for the application to send KPIs and receive notifications. operationId: createSession + security: + - openId: + - session-insights:sessions:create parameters: - $ref: "#/components/parameters/x-correlator" requestBody: @@ -159,6 +166,9 @@ paths: Retrieve the details of a specific session by its operator-assigned session ID. operationId: getSession + security: + - openId: + - session-insights:sessions:read parameters: - name: sessionId in: path @@ -194,6 +204,9 @@ paths: Delete a session by its operator-assigned session ID. This will stop all notifications and metrics streaming for the session. operationId: deleteSession + security: + - openId: + - session-insights:sessions:delete parameters: - name: sessionId in: path @@ -231,6 +244,9 @@ paths: - The request must include a `device` object if using a two-legged token. If using a three-legged token, do not provide a `device` as the device is derived from the token. operationId: retrieveSessionsByDevice + security: + - openId: + - session-insights:sessions:retrieve-by-device parameters: - $ref: "#/components/parameters/x-correlator" requestBody: @@ -274,6 +290,9 @@ paths: evaluate session quality and trigger notifications if thresholds are breached. operationId: sendSessionMetrics + security: + - openId: + - session-insights:sessions:send-metrics parameters: - name: sessionId in: path @@ -322,6 +341,11 @@ components: schema: $ref: "#/components/schemas/XCorrelator" + securitySchemes: + openId: + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration + schemas: XCorrelator: type: string