openapi: 3.0.3
info:
title: Global System for Mobile Communications GSMA Camara Project Device Roaming Status
description: >
This API provides the API consumer with the ability to query device roaming
Status
# Introduction
## Roaming Status
API consumer is able to verify whether a certain user device is in roaming
situation (or not).
The verification of the roaming situation depends on the network's ability.
Additionally to the roaming status, when the device is in roaming situation,
visited country information could be returned in the response.
## Possible Use-Cases
Roaming status verification could be useful in scenario such as (not
exhaustive):
- For regulatory reasons, where a customer may need to be within a certain jurisdiction, or out with others, in order for transactions to be authorized
- For security / fraud reasons, to establish that a customer is located where they claim to be
- For service delivery reasons, to ensure that the customer has access to particular service, and will not incur roaming charges in accessing them
## Relevant terms and definitions
* **Device**: A device refers to any physical entity that can connect to a
network and participate in network communication.
At least one identifier for the device (user equipment) out of four options: IPv4 address, IPv6 address, Phone number, or Network Access Identifier (not supported for this API version) assigned by the mobile network operator for the device.
* **Roaming** : Roaming status - `true`, if device is in roaming situation -
`false` else.
* **Country** : Country code and name - visited country information,
provided if the device is in roaming situation.
* **LastStatusTime** : This property specifies the time when the status was
last updated. Its presence in the response indicates the freshness of the
information, while its absence implies the information may be outdated or
its freshness is uncertain.
# API Functionality
The API exposes following capabilities:
## Device roaming situation
The endpoint `POST /retrieve` allows to get roaming status and country
information (if device in roaming situation) synchronously.
### Authorization and authentication
The "Camara Security and Interoperability Profile" provides details on how a
client requests an access token. Please refer to Identify and Consent
Management (https://github.com/camaraproject/IdentityAndConsentManagement/)
for the released version of the Profile.
Which specific authorization flows are to be used will be determined during
onboarding process, happening between the API Client and the Telco Operator
exposing the API, taking into account the declared purpose for accessing the
API, while also being subject to the prevailing legal framework dictated by
local legislation.
It is important to remark that in cases where personal user data is
processed by the API, and users can exercise their rights through mechanisms
such as opt-in and/or opt-out, the use of 3-legged access tokens becomes
mandatory. This measure ensures that the API remains in strict compliance
with user privacy preferences and regulatory obligations, upholding the
principles of transparency and user-centric data control.
# 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 uniquely 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:
### 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 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.
# Further info and support
(FAQs will be added in a later version of the documentation)
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 0.6.1
x-camara-commonalities: 0.4.0
externalDocs:
description: Product documentation at CAMARA
url: https://github.com/camaraproject/DeviceStatus
servers:
- url: '{apiRoot}/device-roaming-status/v0.6'
variables:
apiRoot:
default: http://localhost:9091
description: API root
tags:
- name: Roaming Status Retrieval
description: >-
Operation to get device roaming status and country information (if
roaming) synchronously
paths:
/retrieve:
post:
tags:
- Roaming Status Retrieval
summary: Global System for Mobile Communications Get the current roaming status and the country information
description: Get the current roaming status and the country information
operationId: getRoamingStatus
parameters:
- $ref: '#/components/parameters/x-correlator'
security:
- openId:
- device-roaming-status:read
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RoamingStatusRequest'
required: true
responses:
'200':
description: Contains information about current roaming status
headers:
x-correlator:
$ref: '#/components/headers/x-correlator'
content:
application/json:
schema:
$ref: '#/components/schemas/RoamingStatusResponse'
examples:
No-Country-Name:
value:
lastStatusTime: '2024-02-20T10:41:38.657Z'
roaming: true
countryCode: 901
countryName: []
Single-Country-Code:
value:
lastStatusTime: '2024-02-20T10:41:38.657Z'
roaming: true
countryCode: 262
countryName:
- DE
Multiple-Country-Codes:
value:
lastStatusTime: '2024-02-20T10:41:38.657Z'
roaming: true
countryCode: 340
countryName:
- BL
- GF
- GP
- MF
- MQ
'400':
$ref: '#/components/responses/Generic400'
'401':
$ref: '#/components/responses/Generic401'
'403':
$ref: '#/components/responses/Generic403'
'404':
$ref: '#/components/responses/Generic404'
'406':
$ref: '#/components/responses/Generic406'
'415':
$ref: '#/components/responses/Generic415'
'422':
$ref: '#/components/responses/Generic422'
'429':
$ref: '#/components/responses/Generic429'
'500':
$ref: '#/components/responses/Generic500'
'501':
$ref: '#/components/responses/Generic501'
'502':
$ref: '#/components/responses/Generic502'
'503':
$ref: '#/components/responses/Generic503'
'504':
$ref: '#/components/responses/Generic504'
components:
securitySchemes:
openId:
type: openIdConnect
openIdConnectUrl: https://example.com/.well-known/openid-configuration
parameters:
x-correlator:
name: x-correlator
in: header
description: Correlation id for the different services
schema:
type: string
headers:
x-correlator:
description: Correlation id for the different services
schema:
type: string
schemas:
RoamingStatusResponse:
type: object
required:
- roaming
properties:
lastStatusTime:
$ref: '#/components/schemas/LastStatusTime'
roaming:
$ref: '#/components/schemas/ActiveRoaming'
countryCode:
$ref: '#/components/schemas/CountryCode'
countryName:
$ref: '#/components/schemas/CountryName'
LastStatusTime:
description: Last time that the associated device roaming status was updated
type: string
format: date-time
example: '2024-02-20T10:41:38.657Z'
ActiveRoaming:
description: Roaming status. True, if it is roaming
type: boolean
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:
* `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:
$ref: '#/components/schemas/DeviceIpv6Address'
minProperties: 1
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,
prefixed with '+'.
type: string
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: [email protected]
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
SingleIpv4Addr:
description: A single IPv4 address with no subnet mask
type: string
format: ipv4
example: 84.125.93.10
Port:
description: TCP or UDP port number
type: integer
minimum: 0
maximum: 65535
DeviceIpv6Address:
description: >
The device should be identified by the observed IPv6 address, or by any
single IPv6 address from within the subnet allocated to the device (e.g.
adding ::0 to the /64 prefix).
type: string
format: ipv6
example: 2001:db8:85a3:8d3:1319:8a2e:370:7344
CountryCode:
description: >-
The Mobile country code (MCC) as an geographic region identifier for the
country and the dependent areas.
type: integer
CountryName:
description: >-
The ISO 3166 ALPHA-2 country-codes of mapped to mobile country
code(MCC). If there is mapping of one MCC to multiple countries, then we
have list of countries. If there is no mapping of MCC to any country,
then an empty array [] shall be returned..
type: array
items:
type: string
RoamingStatusRequest:
description: >-
The request for retrieving the current roaming status for the requested
device.
type: object
properties:
device:
$ref: '#/components/schemas/Device'
ErrorInfo:
description: The error object used for error-cases.
type: object
required:
- status
- code
- message
properties:
status:
type: integer
description: HTTP response status code
code:
type: string
description: Code given to this error
message:
type: string
description: Detailed error description
responses:
Generic400:
description: Problem with the client request
headers:
x-correlator:
$ref: '#/components/headers/x-correlator'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
examples:
GENERIC_400_INVALID_ARGUMENT:
description: Invalid Argument. Generic Syntax Exception
value:
status: 400
code: INVALID_ARGUMENT
message: >-
Client specified an invalid argument, request body or query
param.
Generic401:
description: Unauthorized
headers:
x-correlator:
$ref: '#/components/headers/x-correlator'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
examples:
GENERIC_401_UNAUTHENTICATED:
description: Request cannot be authenticated
value:
status: 401
code: UNAUTHENTICATED
message: >-
Request not authenticated due to missing, invalid, or expired
credentials.
GENERIC_401_AUTHENTICATION_REQUIRED:
description: New authentication is needed, authentication is no longer valid
value:
status: 401
code: AUTHENTICATION_REQUIRED
message: New authentication is required.
Generic403:
description: >
Client does not have sufficient permission.
In addition to regular scenario of `PERMISSION_DENIED`, other scenarios
may exist:
- Phone number cannot be deducted from access token context.(`{"code": "3INVALID_TOKEN_CONTEXT","message": "Phone number cannot be deducted from access token context"}`)
headers:
x-correlator:
$ref: '#/components/headers/x-correlator'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
examples:
GENERIC_403_PERMISSION_DENIED:
description: >-
Permission denied. OAuth2 token access does not have the
required scope or when the user fails operational security
value:
status: 403
code: PERMISSION_DENIED
message: >-
Client does not have sufficient permissions to perform this
action.
GENERIC_403_INVALID_TOKEN_CONTEXT:
description: >-
Reflect some inconsistency between information in some field of
the API and the related OAuth2 Token
value:
status: 403
code: INVALID_TOKEN_CONTEXT
message: '{{field}} is not consistent with access token.'
Generic404:
description: Resource Not Found
headers:
x-correlator:
$ref: '#/components/headers/x-correlator'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
examples:
NOT_FOUND:
value:
status: 404
code: NOT_FOUND
message: The specified resource is not found
DEVICE_IDENTIFIER_NOT_FOUND:
value:
status: 404
code: DEVICE_NOT_FOUND
message: Some identifier cannot be matched to a device
Generic406:
description: Not Acceptable
headers:
x-correlator:
$ref: '#/components/headers/x-correlator'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
examples:
GENERIC_406_NOT_ACCEPTABLE:
description: >-
API Server does not accept the media type (`Accept-*` header)
indicated by API client
value:
status: 406
code: NOT_ACCEPTABLE
message: >-
The server cannot produce a response matching the content
requested by the client through `Accept-*` headers.
Generic415:
description: Unsupported Media Type
headers:
x-correlator:
$ref: '#/components/headers/x-correlator'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
examples:
GENERIC_415_UNSUPPORTED_MEDIA_TYPE:
description: >-
Payload format of the request is in an unsupported format by the
Server. Should not happen
value:
status: 415
code: UNSUPPORTED_MEDIA_TYPE
message: >-
The server refuses to accept the request because the payload
format is in an unsupported format.
Generic422:
description: Unprocessable Entity
headers:
x-correlator:
$ref: '#/components/headers/x-correlator'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
examples:
GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH:
description: >-
Inconsistency between device identifiers not pointing to the
same device
value:
status: 422
code: DEVICE_IDENTIFIERS_MISMATCH
message: Provided device identifiers are not consistent.
GENERIC_422_DEVICE_NOT_APPLICABLE:
description: Service is not available for the provided device
value:
status: 422
code: DEVICE_NOT_APPLICABLE
message: The service is not available for the provided device.
GENERIC_422_UNABLE_TO_PROVIDE_ROAMING_STATUS:
value:
status: 422
code: UNABLE_TO_PROVIDE_ROAMING_STATUS
message: Network issue - Unable to provide roaming status
GENERIC_422_UNSUPPORTED_DEVICE_IDENTIFIERS:
value:
status: 422
code: UNSUPPORTED_DEVICE_IDENTIFIERS
message: >-
None of the provided device identifiers is supported by the
implementation
Generic429:
description: Too Many Requests
headers:
x-correlator:
$ref: '#/components/headers/x-correlator'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
examples:
GENERIC_429_QUOTA_EXCEEDED:
description: Request is rejected due to exceeding a business quota limit
value:
status: 429
code: QUOTA_EXCEEDED
message: Either out of resource quota or reaching rate limiting.
GENERIC_429_TOO_MANY_REQUESTS:
description: API Server request limit is overpassed
value:
status: 429
code: TOO_MANY_REQUESTS
message: Either out of resource quota or reaching rate limiting.
Generic500:
description: Internal Server Error
headers:
x-correlator:
$ref: '#/components/headers/x-correlator'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
examples:
GENERIC_500_INTERNAL:
description: Problem in Server side. Regular Server Exception
value:
status: 500
code: INTERNAL
message: Unknown server error. Typically a server bug.
Generic501:
description: Not Implemented
headers:
x-correlator:
$ref: '#/components/headers/x-correlator'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
examples:
GENERIC_501_NOT_IMPLEMENTED:
description: >-
Service not implemented. The use of this code should be avoided
as far as possible to get the objective to reach aligned
implementations
value:
status: 501
code: NOT_IMPLEMENTED
message: This functionality is not implemented yet.
Generic502:
description: Bad Gateway
headers:
x-correlator:
$ref: '#/components/headers/x-correlator'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
examples:
GENERIC_502_BAD_GATEWAY:
description: >-
Internal routing problem in the Server side that blocks to
manage the service properly
value:
status: 502
code: BAD_GATEWAY
message: An upstream internal service cannot be reached.
Generic503:
description: Service Unavailable
headers:
x-correlator:
$ref: '#/components/headers/x-correlator'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
examples:
GENERIC_503_UNAVAILABLE:
description: >-
Service is not available. Temporary situation usually related to
maintenance process in the server side
value:
status: 503
code: UNAVAILABLE
message: Service Unavailable.
Generic504:
description: Gateway Timeout
headers:
x-correlator:
$ref: '#/components/headers/x-correlator'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
examples:
GENERIC_504_TIMEOUT:
description: API Server Timeout
value:
status: 504
code: TIMEOUT
message: Request timeout exceeded.