From a07b55d744073c45e59fc6e3058c71e13b3ad83e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Pe=C3=B1a=20Garc=C3=ADa-Oliva?= Date: Tue, 11 Jun 2024 14:34:45 +0200 Subject: [PATCH 1/9] Proposal to simplify device object and improve interoperability --- artifacts/CAMARA_common.yaml | 8 ----- documentation/API-design-guidelines.md | 43 +++++++++++++++++++++++++- 2 files changed, 42 insertions(+), 9 deletions(-) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index be3c4b6b..c9c51423 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -59,14 +59,11 @@ components: * `ipv4Address` * `ipv6Address` * `phoneNumber` - * `networkAccessIdentifier` NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. type: object properties: phoneNumber: $ref: "#/components/schemas/PhoneNumber" - networkAccessIdentifier: - $ref: "#/components/schemas/NetworkAccessIdentifier" ipv4Address: $ref: "#/components/schemas/DeviceIpv4Addr" ipv6Address: @@ -79,11 +76,6 @@ components: pattern: '^\+[1-9][0-9]{4,14}$' example: "+123456789" - NetworkAccessIdentifier: - description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. - type: string - example: "123456789@domain.com" - DeviceIpv4Addr: type: object description: | diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 1c825041..02ca085b 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -50,7 +50,10 @@ This document captures guidelines for the API design in CAMARA project. These gu - [Polymorphism](#polymorphism) - [11.6 Security definition](#116-security-definition) - [11.6.1 Scope naming](#1161-scope-naming) - - [Examples](#examples) + - [Regarding scope naming for APIs which do not deal with explicit subscriptions, the guidelines are:](#regarding-scope-naming-for-apis-which-do-not-deal-with-explicit-subscriptions-the-guidelines-are) + - [Examples](#examples) + - [Regarding scope naming for APIs which deal with explicit subscriptions, the guidelines propose some changes as compared to the above format and this is described below:](#regarding-scope-naming-for-apis-which-deal-with-explicit-subscriptions-the-guidelines-propose-some-changes-as-compared-to-the-above-format-and-this-is-described-below) + - [API-level scopes (sometimes referred to as wildcard scopes in CAMARA)](#api-level-scopes-sometimes-referred-to-as-wildcard-scopes-in-camara) - [12. Subscription, Notification \& Event](#12-subscription-notification--event) - [12.1 Subscription](#121-subscription) - [Instance-based (implicit) subscription](#instance-based-implicit-subscription) @@ -66,6 +69,7 @@ This document captures guidelines for the API design in CAMARA project. These gu - [Security Considerations](#security-considerations) - [Abuse Protection](#abuse-protection) - [Notification examples](#notification-examples) + - [Appendix A: `info.description` template for `device` identification from access token](#appendix-a-infodescription-template-for-device-identification-from-access-token) ## Common Vocabulary and Acronyms @@ -1704,3 +1708,40 @@ response: ```http 204 No Content ``` + +## Appendix A: `info.description` template for `device` identification from access token + +The documentation template below must be used as part of the API documentation in `info.description` property in the CAMARA API specs which use the `device`object defined in [CAMARA_common.yaml](https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml) artifact. This template provides guidance on how to handle device information in API requests **when using 3-legged access tokens and the device can be uniquely identified by the token**. + + +```md +# Identifying a user device from the access token + +This specification defines the `device` object field as optional in API requests, specifically in cases where the API is accessed using a 3-legged access token and the device can be uniquelly identified by the token. This approach simplifies API usage for API consumers by relying on the device information associated with the access token used to invoke the API. This mechanism reduces the need for multiple identifiers and extensive validation. + +## Handling of device information: + +### Optional device object for 3-legged tokens: + +- When using a 3-legged access token, 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, therefore **it is recommended NOT to include it in these scenarios** to simplify the API usage and avoid additional validations. + +### Validation mechanism: + +- The server will extract the device identification from the access token, if available. +- If the API request additionally includes a `device` object when using a 3-legged access token, the API will validate that the device identifier provided matches the one associated with the access token. +- If there is a mismatch, the API will respond with a 403 - INVALID_TOKEN_CONTEXT error, indicating that the device information in the request does not match the token. + +### Error handling for unidentifiable devices: + +- If the `device` object is not included in the request and the device information cannot be derived from the 3-legged access token, the server will return a 422 `UNIDENTIFIABLE_DEVICE` error. + +### Restrictions for tokens without an associated authenticated identifier: + +- For tokens that do not have an associated authenticated identifier, e.g. 2-legged access tokens, the `device` object MUST be provided in the API request. This ensures that the device identification is explicit and valid for each API call made with these tokens. + +By following these guidelines, API consumers can use the authenticated device identifier associated with 3-legged access tokens, simplifying implementation and validation. This mechanism ensures that device identification is handled efficiently and securely, and appropriately accommodates different token types. +``` + +Depending on the functionality provided by the CAMARA API, some API subprojects may still define other specific identifiers that differs from the common `device` object definition. Not all APIs necessarily have to refer to a user device, e.g. Carrier Billing API only defines a phone number as a way to identify the mobile account to be billed, Know Your Costumer only defines a phone number as a way to identify the associated account data or Home Devices QoD API defines public IP v4 address as a way to identify the user home network. + +Therefore, the mechanism described in this template is not applicable to all APIs, but could be used as way to make `device` object more interoperable and usable for API consumers. From c0dfc8a79078d5f3881eaf6e8c5fbc7631663017 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Pe=C3=B1a=20Garc=C3=ADa-Oliva?= Date: Tue, 11 Jun 2024 16:51:51 +0200 Subject: [PATCH 2/9] Fixed indentation in table of contents --- documentation/API-design-guidelines.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 02ca085b..caf0f895 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -50,10 +50,10 @@ This document captures guidelines for the API design in CAMARA project. These gu - [Polymorphism](#polymorphism) - [11.6 Security definition](#116-security-definition) - [11.6.1 Scope naming](#1161-scope-naming) - - [Regarding scope naming for APIs which do not deal with explicit subscriptions, the guidelines are:](#regarding-scope-naming-for-apis-which-do-not-deal-with-explicit-subscriptions-the-guidelines-are) + - [APIs which do not deal with explicit subscriptions](#apis-which-do-not-deal-with-explicit-subscriptions) - [Examples](#examples) - - [Regarding scope naming for APIs which deal with explicit subscriptions, the guidelines propose some changes as compared to the above format and this is described below:](#regarding-scope-naming-for-apis-which-deal-with-explicit-subscriptions-the-guidelines-propose-some-changes-as-compared-to-the-above-format-and-this-is-described-below) - - [API-level scopes (sometimes referred to as wildcard scopes in CAMARA)](#api-level-scopes-sometimes-referred-to-as-wildcard-scopes-in-camara) + - [APIs which deal with explicit subscriptions](#apis-which-deal-with-explicit-subscriptions) + - [API-level scopes (sometimes referred to as wildcard scopes in CAMARA)](#api-level-scopes-sometimes-referred-to-as-wildcard-scopes-in-camara) - [12. Subscription, Notification \& Event](#12-subscription-notification--event) - [12.1 Subscription](#121-subscription) - [Instance-based (implicit) subscription](#instance-based-implicit-subscription) @@ -1280,7 +1280,9 @@ The [CAMARA API Specification - Authorization and authentication common guidelin #### 11.6.1 Scope naming -#### Regarding scope naming for APIs which do not deal with explicit subscriptions, the guidelines are: +##### APIs which do not deal with explicit subscriptions + +Regarding scope naming for APIs which do not deal with explicit subscriptions, the guidelines are: * Define a scope per API operation with the structure: @@ -1303,6 +1305,7 @@ where - `write` : For operations creating or modifying the resource, when differentiation between `create` and `update` is not needed. * Eventually we may need to add an additional level to the scope, such as `api-name:[resource:]action[:detail]`, to deal with cases when only a set of parameters/information has to be allowed to be returned. Guidelines should be enhanced when those cases happen. + ###### Examples | API | path | method | scope | @@ -1313,8 +1316,9 @@ where
+##### APIs which deal with explicit subscriptions -#### Regarding scope naming for APIs which deal with explicit subscriptions, the guidelines propose some changes as compared to the above format and this is described below: +Regarding scope naming for APIs which deal with explicit subscriptions, the guidelines propose some changes as compared to the above format and this is described below: Scopes should be represented as below for APIs that offer explicit event subscriptions with action read and delete: @@ -1329,7 +1333,8 @@ Event-type: org.camaraproject.device-roaming-subscriptions.v0.roaming-on Grant-level, action on resource: create For e.g. device-roaming-subscriptions:org.camaraproject.device-roaming-subscriptions.v0.roaming-on:create -#### API-level scopes (sometimes referred to as wildcard scopes in CAMARA) +##### API-level scopes (sometimes referred to as wildcard scopes in CAMARA) + The decision on the API-level scopes was made within the [Identity and Consent Management Working Group](https://github.com/camaraproject/IdentityAndConsentManagement) and is documented in the design guidelines to ensure completeness of this document. The scopes will always be those defined in the API Specs YAML files. Thus, a scope would only provide access to all endpoints and resources of an API if it is explicitly defined in the API Spec YAML file and agreed in the corresponding API subproject. From b7f7c76407dfebdfd859cab56576770d8f9c4981 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Pe=C3=B1a=20Garc=C3=ADa-Oliva?= Date: Tue, 11 Jun 2024 17:14:55 +0200 Subject: [PATCH 3/9] Improved descriptions --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index caf0f895..7db7ce93 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1742,7 +1742,7 @@ This specification defines the `device` object field as optional in API requests ### Restrictions for tokens without an associated authenticated identifier: -- For tokens that do not have an associated authenticated identifier, e.g. 2-legged access tokens, the `device` object MUST be provided in the API request. This ensures that the device identification is explicit and valid for each API call made with these tokens. +- For scenarios which do not have a single device identifier associated to the token during the authentication flow, e.g. 2-legged access tokens, the `device` object MUST be provided in the API request. This ensures that the device identification is explicit and valid for each API call made with these tokens. By following these guidelines, API consumers can use the authenticated device identifier associated with 3-legged access tokens, simplifying implementation and validation. This mechanism ensures that device identification is handled efficiently and securely, and appropriately accommodates different token types. ``` From 0eb1d3fed3ff00a2bcce93245fbd883f89dc0e7e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Pe=C3=B1a=20Garc=C3=ADa-Oliva?= Date: Tue, 18 Jun 2024 12:52:31 +0200 Subject: [PATCH 4/9] merge main --- artifacts/CAMARA_common.yaml | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index 3f257ff2..f18ebc33 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -58,11 +58,14 @@ components: * `ipv4Address` * `ipv6Address` * `phoneNumber` + * `networkAccessIdentifier` NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. type: object properties: phoneNumber: $ref: "#/components/schemas/PhoneNumber" + networkAccessIdentifier: + $ref: "#/components/schemas/NetworkAccessIdentifier" ipv4Address: $ref: "#/components/schemas/DeviceIpv4Addr" ipv6Address: @@ -75,6 +78,11 @@ components: pattern: '^\+[1-9][0-9]{4,14}$' example: "+123456789" + NetworkAccessIdentifier: + description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. + type: string + example: "123456789@domain.com" + DeviceIpv4Addr: type: object description: | From 4ae03bb1d76be80243badfdce988a8b254df0b76 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Pe=C3=B1a=20Garc=C3=ADa-Oliva?= Date: Tue, 18 Jun 2024 13:02:39 +0200 Subject: [PATCH 5/9] Apply middle way agreement --- artifacts/CAMARA_common.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index f18ebc33..392dc53d 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -59,7 +59,8 @@ components: * `ipv6Address` * `phoneNumber` * `networkAccessIdentifier` - NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. + NOTE1: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. + NOTE2: for the Commonalities meta-release v0.4, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the meta-release work is done and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines. type: object properties: phoneNumber: From c1418449ffec79d3a020cb9fcb3fd1e93051fc41 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Pe=C3=B1a=20Garc=C3=ADa-Oliva?= Date: Tue, 18 Jun 2024 17:09:44 +0200 Subject: [PATCH 6/9] Apply Shilpa's suggestion --- artifacts/CAMARA_common.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/CAMARA_common.yaml b/artifacts/CAMARA_common.yaml index 392dc53d..74c8dcaf 100644 --- a/artifacts/CAMARA_common.yaml +++ b/artifacts/CAMARA_common.yaml @@ -60,7 +60,7 @@ components: * `phoneNumber` * `networkAccessIdentifier` NOTE1: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. - NOTE2: for the Commonalities meta-release v0.4, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the meta-release work is done and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines. + NOTE2: for the Commonalities release v0.4, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the CAMARA meta-release work is concluded and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines. type: object properties: phoneNumber: From fb61a6c9493e6d973c1d2813f5e43d829df94fd4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Pe=C3=B1a=20Garc=C3=ADa-Oliva?= Date: Tue, 18 Jun 2024 17:31:49 +0200 Subject: [PATCH 7/9] Add further clarification on 3-legged scenarios where device can be omitted --- documentation/API-design-guidelines.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 3eec0103..95972c87 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -30,8 +30,11 @@ This document captures guidelines for the API design in CAMARA project. These gu - [5.1 Versioning Strategy](#51-versioning-strategy) - [5.2 Backwards and Forward Compatibility](#52-backwards-and-forward-compatibility) - [6. Error Responses](#6-error-responses) - - [### 6.1 Standardized use of CAMARA error responses](#61-standardized-use-of-camara-error-responses) - - [### 6.2 Error Responses - Device Object](#62-error-responses---device-object) + - [6.1 Standardized use of CAMARA error responses](#61-standardized-use-of-camara-error-responses) + - [6.2 Error Responses - Device Object](#62-error-responses---device-object) + - [Templates](#templates) + - [Response template](#response-template) + - [Examples template](#examples-template) - [7. Common Data Types](#7-common-data-types) - [8. Pagination, Sorting and Filtering](#8-pagination-sorting-and-filtering) - [8.1 Pagination](#81-pagination) @@ -43,6 +46,8 @@ This document captures guidelines for the API design in CAMARA project. These gu - [10.2 Security Implementation](#102-security-implementation) - [11. Definition in OpenAPI](#11-definition-in-openapi) - [11.1 General Information](#111-general-information) + - [Info object](#info-object) + - [Servers object](#servers-object) - [11.2 Published Routes](#112-published-routes) - [11.3 Request Parameters](#113-request-parameters) - [11.4 Response Structure](#114-response-structure) @@ -51,6 +56,9 @@ This document captures guidelines for the API design in CAMARA project. These gu - [Inheritance](#inheritance) - [Polymorphism](#polymorphism) - [11.6 Security definition](#116-security-definition) + - [OpenAPI security schemes definition](#openapi-security-schemes-definition) + - [Expressing Security Requirements](#expressing-security-requirements) + - [Mandatory template for `info.description` in CAMARA API specs](#mandatory-template-for-infodescription-in-camara-api-specs) - [11.6.1 Scope naming](#1161-scope-naming) - [APIs which do not deal with explicit subscriptions](#apis-which-do-not-deal-with-explicit-subscriptions) - [Examples](#examples) @@ -1814,6 +1822,7 @@ response: The documentation template below must be used as part of the API documentation in `info.description` property in the CAMARA API specs which use the `device`object defined in [CAMARA_common.yaml](https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml) artifact. This template provides guidance on how to handle device information in API requests **when using 3-legged access tokens and the device can be uniquely identified by the token**. +Note: With the current 3-legged authorization flows, only a single end user can be associated with the access token. For the OIDC authorization code flow, only a single device can call the `/authorize` endpoint and obtain the code. And for CIBA, `login_hint` is currently limited to a single phone number or IP address (that can optionally include a port). ```md # Identifying a user device from the access token From 00684b47bc6e9e54fcff488b56406d3048885778 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Pe=C3=B1a=20Garc=C3=ADa-Oliva?= Date: Tue, 18 Jun 2024 17:36:39 +0200 Subject: [PATCH 8/9] minor fixes --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 95972c87..a60586b7 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1822,7 +1822,7 @@ response: The documentation template below must be used as part of the API documentation in `info.description` property in the CAMARA API specs which use the `device`object defined in [CAMARA_common.yaml](https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml) artifact. This template provides guidance on how to handle device information in API requests **when using 3-legged access tokens and the device can be uniquely identified by the token**. -Note: With the current 3-legged authorization flows, only a single end user can be associated with the access token. For the OIDC authorization code flow, only a single device can call the `/authorize` endpoint and obtain the code. And for CIBA, `login_hint` is currently limited to a single phone number or IP address (that can optionally include a port). +Note: With the current 3-legged authorization flows used by CAMARA, only a single end user can be associated with the access token. For the OIDC authorization code flow, only a single device can call the `/authorize` endpoint and obtain the code. And for CIBA, `login_hint` is currently limited to a single phone number or IP address (which can optionally include a port). ```md # Identifying a user device from the access token From d4d44f5b72675d10192bc8fdceb21b299f576ec9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Pe=C3=B1a=20Garc=C3=ADa-Oliva?= Date: Wed, 19 Jun 2024 15:46:24 +0200 Subject: [PATCH 9/9] Apply Herbert's suggestions --- documentation/API-design-guidelines.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index a60586b7..e1873d19 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1820,14 +1820,14 @@ response: ## Appendix A: `info.description` template for `device` identification from access token -The documentation template below must be used as part of the API documentation in `info.description` property in the CAMARA API specs which use the `device`object defined in [CAMARA_common.yaml](https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml) artifact. This template provides guidance on how to handle device information in API requests **when using 3-legged access tokens and the device can be uniquely identified by the token**. +The documentation template below is recommended to be used as part of the API documentation in `info.description` property in the CAMARA API specs which use the `device`object defined in [CAMARA_common.yaml](https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml) artifact. This template provides guidance on how to handle device information in API requests **when using 3-legged access tokens and the device can be uniquely identified by the token**. Note: With the current 3-legged authorization flows used by CAMARA, only a single end user can be associated with the access token. For the OIDC authorization code flow, only a single device can call the `/authorize` endpoint and obtain the code. And for CIBA, `login_hint` is currently limited to a single phone number or IP address (which can optionally include a port). ```md -# Identifying a user device from the access token +# Identifying a device from the access token -This specification defines the `device` object field as optional in API requests, specifically in cases where the API is accessed using a 3-legged access token and the device can be uniquelly identified by the token. This approach simplifies API usage for API consumers by relying on the device information associated with the access token used to invoke the API. This mechanism reduces the need for multiple identifiers and extensive validation. +This specification defines the `device` object field as optional in API requests, specifically in cases where the API is accessed using a 3-legged access token and the device can be uniquelly identified by the token. This approach simplifies API usage for API consumers by relying on the device information associated with the access token used to invoke the API. ## Handling of device information: @@ -1848,10 +1848,10 @@ This specification defines the `device` object field as optional in API requests ### Restrictions for tokens without an associated authenticated identifier: - For scenarios which do not have a single device identifier associated to the token during the authentication flow, e.g. 2-legged access tokens, the `device` object MUST be provided in the API request. This ensures that the device identification is explicit and valid for each API call made with these tokens. +``` By following these guidelines, API consumers can use the authenticated device identifier associated with 3-legged access tokens, simplifying implementation and validation. This mechanism ensures that device identification is handled efficiently and securely, and appropriately accommodates different token types. -``` -Depending on the functionality provided by the CAMARA API, some API subprojects may still define other specific identifiers that differs from the common `device` object definition. Not all APIs necessarily have to refer to a user device, e.g. Carrier Billing API only defines a phone number as a way to identify the mobile account to be billed, Know Your Costumer only defines a phone number as a way to identify the associated account data or Home Devices QoD API defines public IP v4 address as a way to identify the user home network. +Depending on the functionality provided by the CAMARA API, some API subprojects may still define other specific identifiers that differs from the common `device` object definition. Not all APIs necessarily have to refer to a device, e.g. Carrier Billing API only defines a phone number as a way to identify the mobile account to be billed, Know Your Costumer only defines a phone number as a way to identify the associated account data or Home Devices QoD API defines public IP v4 address as a way to identify the user home network. Therefore, the mechanism described in this template is not applicable to all APIs, but could be used as way to make `device` object more interoperable and usable for API consumers.