New API Proposal - Consent URL API

documentation/API proposals/API_Proposal_Consent_URL_API.md

@@ -0,0 +1,12 @@
+| **Field** | Description | 
+| ---- | ----- |
+| API family name | Consent URL API (TBC)| 
+| API family owner | Telefonica |
+| API summary | **Disclaimer** This API proposal DO NOT aim for delegating consent or privacy management. Operator remains under control of the process while develoepr is just in charge of exposing the capture URL webpage to the user.<br><br>Current consent management is based on: <br>- **Frontend flow (Authcode)**: Since the authorization code grant involves the interaction with application front-end, consent can be captured directly from the user through the application browser. Taking advantage of the frontend flow, consent can directly be captured through an interactive dialogue with the End-User,  <br>- **Backend flow (CIBA)**: Out-of-band consent capture is employed in backend flows as part of asynchronous CIBA flow, where operator gets in charge of reaching the End-User and capturing the consent if needed, based on the channels that each operator supports (e.g. push notification with fallback to SMS, etc...).<br> <br> Developers are therefore mandated to capture the consent in the frontend flow, or delegate the moment of capture in the operator, which may or may not be able to reach the customer in a succesful way. <br><br> With the proposed API, the develoepr will be able to retrieve a similar consent webpage URL as is managed in the Frontend flow (Authcode) process, but from a backend server and being able to show it to the customer in any device or application that best fits in the developer's app use case. User can then access this telco webpage using its telco credentials, and provide a clear consent acceptance. <br><br>The API takes advantage of the developer's knowledge of the customers, based on the use case that they manage, to trigger the consent capture process in the moment and channel that best fit with each customer, while ensuring that the privacy management and ownership remains in the operator. The process can be included in onboarding processes, where developer can gather the consent in advance getting ready by the moment the API(s) need to be called. <br><br> Scenarios to cover:<br> - Pure backend services where no user device is involved, it is, no possibility for a frontend flow. There are a lot of antifraud use cases that do not require a pure user action to be executed (as application checks are done in background), therefore we cannot count on the user been on a device APP. <br> - Services that are executed over a device which has no user interaction possibilities.<br> - Consent capture campaigns without frontend flows. <br><br> _Special considerations, following those applied to CIBA/AuthCode Access Token retrieval mechanisms, will need to be implemented to avoid this API to be used as telco-finder to determine whether the user phone number is in use or whether it belongs to a certain operator._  |
+| Technical viability | The API creates a consent capture URL, provided by the operator and following same or similar interactive dialogue as in frontend flow, that allows the developer to provide a consent capture process to the end-user, based on the requested API scope and purpose that the developer is later going to use. <br>**Inputs Explained:**<br>- **User identifier**: Phone number of the end-user, which identifies the line whose consent is required to access the specific service.<br>- **Scope**: List of API PIScope(s) and a specific  purpose, following the format defined by [CAMARA-API-access-and-user-consent.md](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md) <br>**Output:**<br>- **Consent URL**: URL containing the telco webpage for consent capture, including its own subscriber authentication with telco credentials. <br> _Technical details on URL format and webpage may be defined during specification process._|
+| Commercial viability | **Current use cases validating the service:**<br> 1. **Consent capture during end-user onboarding**: The developer, when registering the user in a digital or physical procedure, can take advantage of the presence of the end-user during the process to pre-capture the consent for the set of APIs that the user is later going to require. <br> 2. **Consent capture in application notification**: Developers can push a notification in their app so that customers can access directly to the consent capture process in this easy-to-access place. <br> 3. **Consent capture campaigns**: Applications can create campaigns by email or other channels to capture the consent for substantial chunks of their user base. | 
+| YAML code available? | NO<br> To be provided  |
+| Validated in lab/productive environments? | YES |
+| Validated with real customers? | YES |
+| Validated with operators? | NO<br> |
+| Supporters in API Backlog Working Group | Telefonica |

documentation/SupportingDocuments/Out_of_band Consent URL API user story.md

@@ -0,0 +1,11 @@
+# Consent URL API User Story
+
+
+| **Item** | **Details** |
+| ---- | ------- |
+| ***Summary*** | As an enterprise application developer, I want my customer (end-user) to provide the consent to access certain CAMARA API before the actual API call is made, taking advantage of, for example, my onboarding process. |
+| ***Roles, Actors and Scope*** | **Roles:** Customer:User, Customer:BusinessManager, Customer:Administrator,<br> End-user, Communication Service Provider (CSP), Channel Partner <br> **Actors:** End-user, Communication Service Provider (CSP), Channel Partner <br> **Scope:**  <br> - Retrieves a consent capture URL based on the required services, so end-user can accept/deny consent in a CSP webpage. |
+| ***Pre-conditions*** |The preconditions are listed below:<br><ol><li>The Customer:BusinessManager and Customer:Administrator have been onboarded to the CSP's API platform.</li><li>The Customer:Administrator has onboarded the Customer:User to the platform.</li><li>The Customer:User performs an authorization request to CSP</li><li>The Customer:User has the access token allowing a secure access of the API.|
+| ***Activities/Steps*** | **Starts when:** The customer application makes a request to the Consent URL API, including the end-user identifier whose consent will be retrieved, the scope(s) of the services requested and the purpose associated to them.<br>**Ends when:** The CSP provides the CSP's consent webpage URL to the customer application. |
+| ***Post-conditions*** | The customer application can show the provided CSP's webpage to the end-user, where end-user will introduce CSP's end-user credentials to provide the required consent (or refuse it). |
+| ***Exceptions*** | Several exceptions might occur during the Consent URL API operations<br>- Unauthorized: Not valid credentials (e.g., use of already expired access token).<br>- Invalid input: Not valid input data to invoke operation (e.g., improperly formatted end-user identifier).<br>- Scopes or purpose not compatible.|