openapi: 3.0.3 info: title: CAMARA Device Identifier API version: 0.1.0 description: | # Summary The Device Identifier API returns details of the mobile device (also know as the UE, or User Equipment) currently being used by a specified mobile subscriber. The following information can be returned: - A unique network identifier for the specific device itself (IMEI SV and IMEI) - A network identifier for the device make and model (IMEI Type Allocation Code) - Device manufacturer name and model This information can be useful in a number of scenarios, such as the following: - For insurance purposes, to automatically identify a device that a customer wishes to insure - For security / fraud reasons, to establish that a customer is not using a device they claim to have broken or lost - For service delivery reasons, to optimise content for a particular device or OS type # Introduction Mobile devices are alloacted a unique identity by the manufacturer, known as the International Mobile Equipment Identity, or IMEI. The current software version (SV) of the device can be appended to this, in which case the identifier is known as the IMEI SV. This identity is signalled to the mobile network when the device connects, both to confirm that the device is not blocked, and also allow device dependent network configurations to be implemented. The IMEI is a 15 digit integer, and the IMEI SV is a 16 digit integer: - The first 8 digits are known as the Type Allocation Code (TAC), and identify the manufacturer and model of the device - The following 6 digits are the serial number of the device for that TAC - For IMEI, the remaining digit is a check digit - For IMEI SV, the remaining two digits are the software version TACs are issued and managed by the GSMA, and can be queried using the [GSMA IMEI database](https://www.gsma.com/aboutus/workinggroups/terminal-steering-group/imei-database). The mobile network associates this device identifier with the mobile subscription currently using the device. The mobile subscription is defined by the Subscriber Identity Module (SIM) currently active in the mobile device. This may be a removable SIM or an eSIM. In either case, it is possible for the association between the device identifier and subscription to change - for example, when a physical SIM is transferred to another mobile device. ![Device Identifier API Overview](https://raw.githubusercontent.com/camaraproject/DeviceIdentifier/main/documentation/API_documentation/resources/Device_Identifier_Overview.png) The Device Identifier API allows the API consumer to obtain the IMEI and associated parameters for a specified mobile subscription identifier or equivalent. The mobile subscription can be identified using one of the following subscription identifiers: - the subscription phone number (also known as MSISDN) - the subscription network access identifier, which is a domain specific identifier typically allocated to devices that do not require voice / SMS connectivity - the current IP address and port alloacted to the device, which must be an IPv6 or public IPv4 address The API can be called by an application server or other 3rd party server to establish the identity of the device currently being used by the mobile subscription. The information returned will depend upon the consent that the end user (i.e. mobile subscription owner) has given for that information to be provided to the API consumer. For example, if the end user has not consented to any information about their device being given, then the API consumer will receive an error in reponse to their request. Otherwise, the information that the end user has consented to being given will be returned. # Relevant terms and definitions * *Device Identifier API service endpoint*: The URL pointing to the RESTful resource of the Device Identifier API. * *Authentication*: Security access keys such as OAuth 2.0 client credentials used by client applications to invoke the Device Identifier API. * *Identifier for the mobile subscription*: At least one identifier for the mobile subscription from the following four options: - Phone number (MSISDN) - Network Access Identifier assigned by the mobile network operator for the device - IPv6 address - IPv4 address # API functionality The API defines a single service endpoint `POST /get-device-identifier`. To call this endpoint, the API consumer must first obtain a valid OAuth2 token from the token endpoint, which is then passed as an Authorization header. The API consumer must also pass at least one of the available mobile subscription identifiers in the body of the request. Not all possible mobile subscription identifiers may be valid for a given network or implementation, and hence the API consumer should provide as many identifiers as are known to them. If the API consumer provides identifiers for different mobile subscriptions, the API may return an error, or it may take each identifier provided in the order specified above until it finds a valid subscription identifier. If the authentication token is not valid, a `401 UNAUTHENTICATED` error is returned If the mobile subscription parameters contain a formatting error, a `400 INVALID_ARGUMENT` error is returned. If the mobile subscription cannot be identified from the provided parameters, a `404 NOT_FOUND` error is returned. If the end user has not consented to the API consumer getting access to the device identifier information, then a `403 PERMISSION_DENIED` error is returned. Otherwise, a JSON object is returned containing the data the the end user has consented to sharing with the API consumer. An example of this JSON object is as follows: { "imeisv": "49015420323751800", "imei": "4901542032375181", "tac": "49015420", "model": "3110", "manufacturer": "Nokia" } servers: - url: https://apigwsb.omantel.om variables: apiRoot: default: https://apigwsb.omantel.om description: API root basePath: default: /v1/device description: Base path for the Device Identifier API paths: /v1/device/identifier/device-identifier: get: security: - oAuth2ClientCredentials: [] tags: - Get device identifiers summary: Get details about the device being used by a specified mobile subscriber description: Get details about the device being used by a specified mobile subscriber operationId: getDeviceIdentifier parameters: - name: Phone-Number in: header description: Mobile number of the customer with country code. required: true example: '9689259xxxx' schema: type: string minLength: 8 maxLength: 11 - name: mock-key in: query description: The mock-key parameter is used to simulate different response scenarios. Choose one of the available keys. **NOTE:- Mock keys are only applicable for sandbox environment and only give you mock responses.** required: true schema: type: string enum: - device-identifier-get-200 - device-identifier-get-400 - device-identifier-get-401 - device-identifier-get-403 - device-identifier-get-404 - device-identifier-get-405 - device-identifier-get-406 - device-identifier-get-429 - device-identifier-get-500 - device-identifier-get-503 - device-identifier-get-504 responses: "200": $ref: '#/components/responses/200Response' "400": $ref: '#/components/responses/400BadRequest' "401": $ref: '#/components/responses/401Unauthorized' "403": $ref: '#/components/responses/403Forbidden' "404": $ref: '#/components/responses/404NotFound' "405": $ref: '#/components/responses/405MethodNotAllowed' "406": $ref: '#/components/responses/406Unacceptable' "429": $ref: '#/components/responses/429TooManyRequests' "500": $ref: '#/components/responses/500InternalServerError' "502": $ref: '#/components/responses/502BadGateway' "503": $ref: '#/components/responses/503ServiceUnavailable' "504": $ref: '#/components/responses/504GatewayTimeout' components: securitySchemes: oAuth2ClientCredentials: type: oauth2 flows: clientCredentials: tokenUrl: https://apigwsb.omantel.om/oauth2/accesstoken scopes: get-device-identifier: get-device-identifier operation responses: 200Response: description: An device identifier has been found for the specified subscriber content: application/json: schema: type: object properties: imeisv: type: string description: IMEISV of the device example: "49015420323751800" imei: type: string description: IMEI of the device example: "4901542032375181" tac: type: string description: IMEI TAC of the device example: "49015420" model: type: string description: Model of the device example: "3110" manufacturer: type: string description: Manufacturer of the device example: "Nokia" 400BadRequest: description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: InsufficientParameters: description: Sufficient parameters must be provided to allow the target UE to be identified value: status: 400 code: INVALID_ARGUMENT message: "At least one of phoneNumber, networkAccessIdentifier, ipv4Address and ipv6Address msut be specified" InconsistentDeviceProperties: description: Device parameters provided identify different devices value: status: 400 code: INVALID_ARGUMENT message: "Multiple inconsistent device parameters specified" InvalidExternalId: value: status: 400 code: INVALID_ARGUMENT message: "Invalid format: networkAccessIdentifier" InvalidMSISDN: value: status: 400 code: INVALID_ARGUMENT message: "Invalid format: phoneNumber" InvalidIPv4: value: status: 400 code: INVALID_ARGUMENT message: "Invalid format: ipv4Address" InvalidIPv6: value: status: 400 code: INVALID_ARGUMENT message: "Invalid format: ipv6Address" InvalidPort: value: status: 400 code: OUT_OF_RANGE message: "Invalid value: ipv4Address.publicPort" 401Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: InvalidCredentials: value: status: 400 code: UNAUTHENTICATED message: "Request not authenticated due to missing, invalid, or expired credentials" 403Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: InsufficientPermissions: value: status: 403 code: PERMISSION_DENIED message: "API consumer does not have sufficient permissions to perform this action" 404NotFound: description: Subscriber Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: SubscriberNotFound: description: The specified parameters are either inconsistent (if multiple parameters are specified) or not currently associated with any customers of this service value: status: 404 code: NOT_FOUND message: "No device found for the specified parameters" 405MethodNotAllowed: description: Method Not Allowed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: MethodNotAllowed: description: An HTTP verb other than GET has been used to try and access the resource value: status: 404 code: METHOD_NOT_ALLOWED message: "The request method is not supported by this resource" 406Unacceptable: description: Not Acceptable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: NotAcceptable: description: A response format other than JSON has been requested value: status: 406 code: NOT_ACCEPTABLE message: "The server cannot produce a response matching the content requested by the client through Accept-* headers" 429TooManyRequests: description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: TooManyRequests: description: Access to the API has been temporarily blocked due to quota or spike arrest limits being reached value: status: 429 code: TOO_MANY_REQUESTS message: "Either out of resource quota or reaching rate limiting" 500InternalServerError: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: 500 code: INTERNAL message: "The service is currently not available" 502BadGateway: description: Bad Gateway content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: 502 code: BAD_GATEWAY message: "The service is currently not available" 503ServiceUnavailable: description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: 503 code: UNAVAILABLE message: "The service is currently not available" 504GatewayTimeout: description: Gateway Time-Out content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: 504 code: TIMEOUT message: "The service is currently not available" schemas: Device: description: | End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators. The developer can choose to provide the below specified device identifiers: * `phoneNumber` * `networkAccessIdentifier` * `ipv6Address` * `ipv4Address` NOTE: The API implementation might support only a subset of these options. The API consumer can provide multiple identifiers to be compatible across different implementations. In this case the identifiers MUST belong to the same device. In the event that the identifiers belong to different devices, an error may be returned, or the API implementation may take the identifiers specified in the order defined above until it finds a valid identifier. type: object properties: phoneNumber: $ref: "#/components/schemas/PhoneNumber" networkAccessIdentifier: $ref: "#/components/schemas/NetworkAccessIdentifier" ipv6Address: $ref: "#/components/schemas/Ipv6Address" ipv4Address: $ref: "#/components/schemas/DeviceIpv4Addr" minProperties: 1 DeviceIpv4Addr: type: object description: | The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers). If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress. If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object) In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone. properties: publicAddress: $ref: "#/components/schemas/SingleIpv4Addr" privateAddress: $ref: "#/components/schemas/SingleIpv4Addr" publicPort: $ref: "#/components/schemas/Port" anyOf: - required: [publicAddress, privateAddress] - required: [publicAddress, publicPort] example: { "publicAddress": "84.125.93.10", "publicPort": 59765 } ErrorResponse: type: object properties: code: type: string description: A short, human-readable summary of the problem type status: type: integer description: The HTTP status code message: type: string description: This parameter appears when there was an error. Human readable explanation specific to this occurrence of the problem Ipv6Address: type: string allOf: - pattern: '^((:|(0?|([1-9a-f][0-9a-f]{0,3}))):)((0?|([1-9a-f][0-9a-f]{0,3})):){0,6}(:|(0?|([1-9a-f][0-9a-f]{0,3})))(\/(([0-9])|([0-9]{2})|(1[0-1][0-9])|(12[0-8])))?$' - pattern: '^((([^:]+:){7}([^:]+))|((([^:]+:)[^:]+)?::(([^:]+:)[^:]+)?))(\/.+)?$' example: "2001:db8:85a3:8d3:1319:8a2e:370:7344" description: | IPv6 address, following IETF 5952 format, may be specified in form
as: - address - The /128 subnet is optional for single addresses: - 2001:db8:85a3:8d3:1319:8a2e:370:7344 - 2001:db8:85a3:8d3:1319:8a2e:370:7344/128 - address/mask - an IP v6 number with a mask: - 2001:db8:85a3:8d3::0/64 - 2001:db8:85a3:8d3::/64 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" PhoneNumber: description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, optionally prefixed with '+'. type: string pattern: '^\+?[0-9]{5,15}$' example: "123456789" Port: description: TCP or UDP port number type: integer minimum: 1024 maximum: 65535 SingleIpv4Addr: description: A single IPv4 address with no subnet mask type: string pattern: '^(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])$' example: "84.125.93.10"