API_Proposal_Consent_URL_API.md
July 15, 2025 ยท View on GitHub
| Field | Description |
|---|---|
| API family name | Consent Info API |
| API family owner | Telefonica |
| API summary | Disclaimer This API proposal DO NOT aim to delegate consent or privacy management. The Operator remains in full control of the process, while the Developer is only allowed to present the Consent Info API to the end-user. Current consent management is based on: - 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, - 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...). 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. With the proposed API, the developer 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. - Check whether data processing is currently allowed for a given purpose ( statusValidForProcessing).- Understand the reason why processing is not allowed, if applicable ( statusReason). - Request a consent capture URL only when needed ( requestCaptureUrl = true) to present to the user. This check can be performed independently of whether a capture URL is requested, allowing the developer to verify if consent is already in place before triggering any user interaction. The user can then access this telco webpage using its telco credentials and provide a clear consent acceptance. Additionally, developer will be able to receive information on consent/lawful base status. 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. Scenarios to cover: - 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. - Services that are executed over a device which has no user interaction possibilities. - Consent capture campaigns without frontend flows. 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. Inputs Explained: - User identifier: Phone number of the end-user, which identifies the line whose consent is required to access the specific service. - Scope: List of API PIScope(s) and a specific purpose, following the format defined by CAMARA-API-access-and-user-consent.md Output: -statusValidForProcessing: Boolean indicating whether the requested data processing is currently permitted. - statusReason (optional): String indicating the reason if processing is not permitted. -Consent URL (optional): Provided only if requestCaptureUrl = true. URL containing the telco webpage for consent capture, including its own subscriber authentication with telco credentials. Technical details on URL format and webpage may be defined during specification process. |
| Commercial viability | Current use cases validating the service: 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. 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. 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 To be provided |