Resource-based subscription – GET /subscriptions using a 3-legged access token

[JoachimDahlgren]

Problem description
When creating a resource-based subscription to information related to a device (such as location, roaming status etc) there is today in the POST /subscription subscriptionDetail a device object to indicate which device the subscription relates to.

In case a 3-legged access token is used it is assumed that “the device associated with the access token must be considered as the device for the API request. This means that the device object is not required in the request, and if included it must identify the same device.”

But how should the usage of a 3-legged access token be interpreted when used with GET /subscriptions, GET /subscriptions/{subscriptionId} or DELETE /subscriptions/{subscriptionId} in which the device is not part of the request parameters?

Possible evolution
Describe the expected behavior, in the API-design-guidelines Subscription chapter, when using a 3-legged access token when invoking

1. POST /subscriptions in cases when there is a device object in the subscriptionDetail
2. GET /subscriptions and GET /subscriptions/{subscriptionId}
3. DELETE /subscriptions/{subscriptionId}

Alternative solution
On one hand it would be natural to view device information in the access token as a filter. On the other hand it would be difficult for an application to get a list of all its subscriptions no matter which device it involves with less than having a separate 2-legged access token for that purpose.

Additional context

[eric-murray]

Hi @JoachimDahlgren

Generally, if the API consumer uses a 3-legged token, this implies that end user consent is required for the scope being used to access the API, and hence the API should only process the data for that end user. However, this may not always be the case, as end user consent requirements depend very much on local regulation.

And for subscriptions, there is the additional question that, if an end user has consented to the creation of a subscription, have they effectively also consented to that subscription being queried or deleted? In other words, does the mere existence of a subscription automatically imply that the end user has consented that being queried or deleted? CAMARA cannot answer that question.

So I think the best CAMARA can do is clarify the rules for the general case. Currently, a 3-legged token can only identify a single end user (in the case of mobile networks, a single end user subscription). And all endpoints have an associated scope and, for subscriptions, usually the scopes to create, query or delete a subscription are different, implying that the end user may separately need to consent to each.

So I think the general rules need to be:

POST /subscriptions:

• 3-legged token: Create the subscription for the end user identified by the token
• 2-legged token: Create the subscription for the end user identified by config -> subscriptionDetail -> device

GET /subscriptions:

• 3-legged token: Return all subscriptions created by the API consumer for the end user identified by the token (i.e. a filter)
• 2-legged token: Return all subscriptions created by the API consumer

GET /subscriptions/{subscriptionId}:

• 3-legged token: Return details of subscriptionId if the associated end user matches the end user identified by the token
• 2-legged token: Return details of subscriptionId

DELETE /subscriptions/{subscriptionId}:

• 3-legged token: Delete subscriptionId if the associated end user matches the end user identified by the token
• 2-legged token: Delete subscriptionId

Additional comments:

• The current subscription pattern mandates that the subscription creation request explicitly includes an end user identifier. I think this needs to be optional, and not provided if the subscription is created using a 3-legged token.
• API providers should be careful not to allow end users to consent to subscription creation, but not to consent to subscription deletion

[jlurien]

The question is extensible to any API creating/managing resources which are associated to a user or device and may be managed knowing its identifier. For example, in QoD we had a similar discussion regarding sessions. There, we have stated that:

For GET / DELETE by id:

• The access token may be either 2-legged or 3-legged.
• If a 3-legged access token is used, the end user (and device) associated with the session must also be associated with the access token.
• The session must must have been created by the same API client given in the access token

There is no operation to list all sessions, but there is a GET by device, and in that case:

• The access token may be either 2-legged or 3-legged.
  • If a 3-legged access token is used, the end user (and device) associated with the session must also be associated with the access token. In this case it is recommended NOT to include the device parameter in the request (see "Handling of device information" within the API description for details).
  • If a 2-legged access token is used, the device parameter must be provided and identify a device.
• The session must have been created by the same API client given in the access token

This is quite aligned with the proposal by @eric-murray, only adding that for

GET /subscriptions/{subscriptionId}:

• 2-legged token: Return details of subscriptionId. The subscription must have been created by the same API client given in the access token

DELETE /subscriptions/{subscriptionId}:

• 2-legged token: Return details of subscriptionId. The subscription must have been created by the same API client given in the access token

[eric-murray]

The subscription must have been created by the same API client given in the access token

Agree, though this applies whether the token is 2- or 3-legged.

[bigludo7]

Hello
This issue is tagged for subscriptions but got the feeling that it scope is larger and Qod Session or Carrier billing payment could also be in same situation.
So I'm not sure it makes sense to add something in part 12 of the design guideline but instead be in a more general part.
What about an additional 11.7 API access restriction (based on token & clientId) - in part 11 ?

cc: @rartych for guidance

[PedroDiez]

Agree this consideration is not only for subscriptions but also for APIs that at least has the concept of resource creation + resource query (POST+GET) within their functionality