Eligibility-Info/Pre-flight API proposal

[shilpa-padgaonkar]

What type of PR is this?

Add one of the following kinds:

• enhancement/feature
• documentation

What this PR does / why we need it:

API proposal for Eligibility-Info or Preflight API

Which issue(s) this PR fixes:

Fixes #323

Special notes for reviewers:

Changelog input

 release-note

Additional documentation

This section can be blank.

docs

[albertoramosmonagas]

Hi @shilpa-padgaonkar, thanks for submitting the API proposal.

As an initial review from the API Backlog side, I see value in the problem statement, but I think a few points need to be clarified before the Backlog WG can validate the proposal for onboarding:

1. The supporting PPT/deck to be presented in the next API Backlog WG session is currently missing. Please upload it to the issue/PR so that participants can review it in advance. This API proposal is already included in the agenda for the next Backlog WG session (25th June)

2. At first sight, this could fit CAMARA as a Service Management API, provided that it is limited to checking runtime eligibility/applicability of CAMARA Service APIs for a given scope/purpose/subscriber context. Please explicitly clarify that the API is not intended to cover Operate API capabilities such as product catalogue, pricing, onboarding, provisioning, settlement, billing, partner fulfilment or assurance.

3. The current YAML states that this is a Client Credentials API and that the phone number is explicitly provided in the request body. This needs careful review with ICM, because subscriber-specific eligibility checks may involve Personal Data or user-related information. Please clarify:

• whether the API has two separate modes: application/API-level eligibility without subscriber data vs subscriber-specific eligibility;
• which authorization flows are expected for each mode;
• whether subscriber-specific checks require a three-legged/user-bound flow such as JWT Bearer, CIBA or Authorization Code;
• how legal basis, purpose and consent/opt-out rules are evaluated.

4. The proposal introduces an eligibilityResponseId that may be passed later as x-eligibility-response-id to downstream service APIs. This has a potential cross-CAMARA impact. Please clarify whether this ID is:

• only an optional optimization hint; or
• expected to be normative and supported by other CAMARA APIs.

In any case, it must not replace the normal OAuth/OIDC access token validation performed by the Resource Server. If kept, the binding model needs to be specified: client_id, subscriber/user identifier, provider, scopes, purpose, expiry/TTL, API/version and replay protection.

5. The current response model includes context codes such as subscriber not supported, subscription cancelled and privacy opt-out. These may reveal sensitive subscriber or operator information and could create telco-finder/subscriber-enumeration risks. Please explain the mitigation strategy and whether the API should expose only privacy-preserving outcomes such as eligible / not eligible / unknown / temporarily unavailable, instead of detailed reasons.

6. The YAML allows checking scopes from multiple APIs in a single request, for example Number Verification and SIM Swap. This means the proposal may affect several existing API repositories/subprojects. Please identify which existing CAMARA APIs are expected to be supported initially and which maintainers/subprojects should review the proposal. At minimum, I would expect review from ICM, Commonalities and the maintainers of the APIs used as normative examples.

[shilpa-padgaonkar]

@albertoramosmonagas : Thanks for your comments. Please see my responses below:

Hi @shilpa-padgaonkar, thanks for submitting the API proposal.

As an initial review from the API Backlog side, I see value in the problem statement, but I think a few points need to be clarified before the Backlog WG can validate the proposal for onboarding:

1. The supporting PPT/deck to be presented in the next API Backlog WG session is currently missing. Please upload it to the issue/PR so that participants can review it in advance. This API proposal is already included in the agenda for the next Backlog WG session (25th June)

-- Sure, since the YAML was uploaded, I thought we might not need a PPT :). But we can upload one.

2. At first sight, this could fit CAMARA as a Service Management API, provided that it is limited to checking runtime eligibility/applicability of CAMARA Service APIs for a given scope/purpose/subscriber context. Please explicitly clarify that the API is not intended to cover Operate API capabilities such as product catalogue, pricing, onboarding, provisioning, settlement, billing, partner fulfilment or assurance.

-- Yes, its not intended to cover operate API capabilities.

3. The current YAML states that this is a Client Credentials API and that the phone number is explicitly provided in the request body. This needs careful review with ICM, because subscriber-specific eligibility checks may involve Personal Data or user-related information. Please clarify:

• whether the API has two separate modes: application/API-level eligibility without subscriber data vs subscriber-specific eligibility;
• which authorization flows are expected for each mode;
• whether subscriber-specific checks require a three-legged/user-bound flow such as JWT Bearer, CIBA or Authorization Code;
• how legal basis, purpose and consent/opt-out rules are evaluated.

--We can use the usual rule here, where MSISDN is optional when 3-legged-access-token exists and when not, msisdn needs to be part of request. The fact that it supports multiple scopes is in line with Camara ICM, where as long as the purpose is the same, multiple scopes (spanning across APIs) can be part of the request. The application context only means that API consumers can check eligibility for mulitple API scopes (requested by an application) as long as the purpose is the same.

4. The proposal introduces an eligibilityResponseId that may be passed later as x-eligibility-response-id to downstream service APIs. This has a potential cross-CAMARA impact. Please clarify whether this ID is:

• only an optional optimization hint; or
• expected to be normative and supported by other CAMARA APIs.

-- It is optional optimization hint. API providers can decide to support it in combination with the Camara service APIs they deem appropriate.

In any case, it must not replace the normal OAuth/OIDC access token validation performed by the Resource Server. If kept, the binding model needs to be specified: client_id, subscriber/user identifier, provider, scopes, purpose, expiry/TTL, API/version and replay protection.

-- This does not replace normal OAuth/OIDC flows.

5. The current response model includes context codes such as subscriber not supported, subscription cancelled and privacy opt-out. These may reveal sensitive subscriber or operator information and could create telco-finder/subscriber-enumeration risks. Please explain the mitigation strategy and whether the API should expose only privacy-preserving outcomes such as eligible / not eligible / unknown / temporarily unavailable, instead of detailed reasons.

--API providers not supporting these values can refrain from using them. Use of context code is optional.

6. The YAML allows checking scopes from multiple APIs in a single request, for example Number Verification and SIM Swap. This means the proposal may affect several existing API repositories/subprojects. Please identify which existing CAMARA APIs are expected to be supported initially and which maintainers/subprojects should review the proposal. At minimum, I would expect review from ICM, Commonalities and the maintainers of the APIs used as normative examples.

--It's in line with Camara and follows the same pattern as used for token request, where as long as purpose is same, multiple scopes can be part of the request. In addition, if API providers would like to only support scopes limiting to a single API, this should also be possible.

[albertoramosmonagas]

Hi @shilpa-padgaonkar,

the PPT it's for presenting it to the other participants at the backlog meeting. It's much easier to show that than a YAML file. API proposals at this stage of development usually don't have a YAML file because they're ideas that are developed later in the repository.

1. Thanks for confirming that this is not intended to cover Operate API capabilities. Please make this explicit in the proposal/deck, positioning the API as a Service Management API and explicitly excluding catalogue, pricing, onboarding, provisioning, settlement, billing, fulfilment and assurance capabilities.
   Multiple scopes with same purpose

2. I agree that requesting multiple scopes with the same purpose is aligned with the ICM model. My concern is not the multi-scope pattern itself, but the fact that this API introduces a common eligibility semantic across scopes belonging to potentially different CAMARA APIs/subprojects. For that reason, I still think the proposal should identify which CAMARA APIs are expected to be supported initially and which API maintainers/subprojects should review the eligibility semantics.

3. Then, for the Authorization model and subscriber identifier handling, your explanation makes sense. However, the current YAML appears to describe the API as Client Credentials based and includes the phone number in the request body. Please update the YAML/proposal to clearly describe the supported modes, for example:

• 3-legged/user-bound mode: subscriber identifier derived from the access token;
• explicit identifier mode: phoneNumber or another identifier included in the request, subject to the applicable legal basis and ICM rules;
• application/API-level eligibility mode, if applicable, without subscriber data.

This distinction is important because subscriber-specific eligibility may involve Personal Data or user-related information

4. I understand that contextCode is optional. However, if sensitive context values are defined in the API contract, they may still create implementation and interoperability expectations. Please clarify the recommended privacy-preserving behavior. In particular, the API should avoid enabling subscriber enumeration or telco-finder behavior. It may be safer to define a small set of generic outcomes such as:

• ELIGIBLE
• NOT_ELIGIBLE
• UNKNOWN
• TEMPORARILY_UNAVAILABLE
  and only expose more detailed context codes where the API provider has confirmed that this is safe and legally supported.

5. Given the ICM and cross-API nature of the proposal, I would still recommend review from:

• ICM WG (@camaraproject/identity-and-consent-management_codeowners)
• Commonalities WG (@camaraproject/commonalities_codeowners)
• maintainers of the APIs used as normative examples or initial supported scopes.

With these updates, I think the proposal will be much easier to assess in the next Backlog WG session.

[shilpa-padgaonkar]

@albertoramosmonagas

For point4:
There is no need to add eligible/not-eligible as part of context code as this is anyways part of response. The codes that are currently part of this spec are already okayed by the contributors of this spec. It is up to the API providers to extend these set of code values as required by their regulatory bodies as IMHO we might never have all values that are unanimously approved across all geographies.

[albertoramosmonagas]

7. I understand that contextCode is optional. However, if sensitive context values are defined in the API contract, they may still create implementation and interoperability expectations. Please clarify the recommended privacy-preserving behavior. In particular, the API should avoid enabling subscriber enumeration or telco-finder behavior. It may be safer to define a small set of generic outcomes such as:

• ELIGIBLE
• NOT_ELIGIBLE
• UNKNOWN
• TEMPORARILY_UNAVAILABLE
  and only expose more detailed context codes where the API provider has confirmed that this is safe and legally supported.

Thanks @shilpa-padgaonkar.

Just to clarify, I was not suggesting that ELIGIBLE / NOT_ELIGIBLE should be added as contextCode values. I agree that eligibility is already conveyed by the main response. My concern is the level of detail exposed through optional contextCode values. Even if optional, detailed reasons such as subscription cancelled or privacy opt-out may create interoperability expectations and expose information that some providers consider sensitive, especially in an API that could be used for subscriber enumeration or telco-finder behavior.

Since we are unlikely to have a globally accepted exhaustive set of context codes, I think the standardized set should remain minimal and privacy-preserving, while allowing provider-specific extensions where legally supported.

In short:

• keep eligibility as the primary outcome;
• standardize only a small set of generic context codes;
• allow provider-specific extensions when needed;
• clarify that detailed context codes are optional and should not be relied upon for portable behavior;
• provide guidance to avoid exposing sensitive information.

This would preserve flexibility while avoiding sensitive context values becoming a de facto CAMARA-wide interoperability expectation.

[PedroDiez]

Some comments from Commonalities perspective:

### API Scope:

• It is indicated "API enables API consumers to determine whether a subscriber is eligible for one or more service API scopes and a purpose". To access to a given resource is not only a matter of the suscription but also the rights given to the API consumer.
  Then, for this API to provide value think it would have to consider the dupla "subscription, API consumer", because some functionality may be accessible for the user itself but not for the API consumer. In case that is not the purpose/aim, maybe it is needed to clarify further the scope of the API and review it.

• About the name maybe "pre-flight" would be better to be reworded in order to not be misunderstood with drones APIs features.

• Is API intended to be only 2-legged?, if so, a hint to identify the subscription is mandatory (e.g. phoneNumber). The challenge here is define the working in a GSMA solution (e.g. routing). In case 3-legged scenario it is also allowed, then it is needed to obtain a token in advance, something that is trying to be simplified by this proposal. This leads to the next question

• What is the (minimum) expected checks covered by this funcionality?

  • I think it MUST NOT cover legal/permissions checks as that funcionality is covered by ConsentInfo and ConsentManagement APIs. That would be needed to explicitly mentioned.

  • In case 3-legged scenario is also allowed, AuthN/AuthZ flows cover authorization checkings, so it seems the scope of this feature is more focused to API Backend checkings. Some explanation about the checkings to be performed would help in the scope, that is, which set of checkings should cover an implementation as a minimum in order to have some aligment in the eligibility value

### API Design:

Request:

• phoneNumber: In case scope is 2/3-legged it MUST be optional and the design needs to cover 422 MISSING_IDENTIFIER/UNNECESSARY_IDENTIFIER.

  • Question for clarification: Why only use phoneNumber for subscription identification, maybe need to use device model

• cspAuthUrlRequired: It seems a facility for API client. This is usually covered by .well-known endpoint by AuthServers. At least, setting to default value "false" would make sense, just to only return it in case the API client explictly requests it (Understand it is only applicable for OIDC Auth Code flow)

Response:

• eligibilityResponseId is an opaque concept/value that actually has underlying metadata which is the "success/error case" of the indicated APIs (by means of the scopes) for the subscription indicated. Therefore, it is later mentioned passing this metadata in subsequent requests using an optional HTTP header (x-eligibility-response-id) to indicate to the API Backend.
• This optional x-eligibility-response-id header would need to be defined in CAMARA Commonalities, specifying the expected behavior when an API Consumer includes it. (NOTE: This header is optional and depends on an API Provider implementing this API and adapting its support to the rest of their API implementations.)

NOTE: The underlying idea (as far as i understand) is that this header serves to "avoid" additional checks and provides a suggestion for a positive or negative response. Even the purpose is that the prior invocation of this eligibility API already provides information on whether an error will occur. So an API Consumer can decide to not trigger specific API request in advance.

• expirationDate and ttl seems to be redundant. I believe it makes more sense to maintain only expirationDate, which reflects an absolute timestamp for the response's validity.

• Performance:

  • since a broad range of scopes could be queried, the response might take some time, so performance can be compromised. Therefore, it may make sense to also define an asynchronous response model (adding sink, sinkCredential in the request and model async response with callback).

NOTE: Error Info model and properties of the API would be needed to be aligned with Commonlities Data types guidance (OWASP related alignment coming from Spring26). Just for having track of it.

[AxelNennker]

I think that eligibilityResponseId is a bearer token and the API should not restrict that to be a uuidv4.

The format should be the choice of the CSP.
Maybe eligibilityResponseId some CSP choose to use JWE(JWS(json)) that contains all the data needed, has an expiration date/time etc and therefore freeing the CSP to store the eligibilityResponseId in a database which needs memory which could be exhausted by a DOS attack.

Note that the auth_req_id from CIBA, which might have been the inspiration for eligibilityResponseId, is restricted to 'A'-'Z', 'a'-'z', '0'-'9', '.', '-' and '_', which are all characters of a JWE compact-serialization.
In CIBA JWE(JWS(json)) is allowed as a auth_req_id.