The following diagram shows an overview of the architecture in place for 1GLOBAL Connect. The partner layer in yellow shows a high-level view of how a final integration should work. 1GLOBAL Connect is responsible for managing all the network and activation requests and provide a simple easy-to-use abstraction interface to our users.

eSIM Profiles

eSIM profiles are electronic versions of a physical SIM. Think of a downloaded video vs a DVD. An eSIM can be downloaded over the internet and installed into a device. The most common method of doing this today is via a QR code or through an iOS, Android or a Microsoft Windows application.

Plans

The 1GLOBAL plan is linked to an eSIM when an order is made via 1GLOBAL Connect API. The end user must install the eSIM to then use the service. Once the eSIM has been installed, the partner can make any number of renewals of the same (or other) plans to the same eSIM, meaning that the end customer does not need a new eSIM for each data plan. Visit the Getting a new eSIM to understand how the process works.

Welcome to the 1GLOBAL Connect developer documentation. Here you can find technical documentation for using the API, recipes on how to implement the most common use-cases, and a complete API reference, including example requests and possible responses.

In order to start using 1GLOBAL Connect you will need to get access to our platform, please visit 1GLOBAL Connect website to learn how.

After getting your credentials please visit our Authentication and Environments sections in order to understand our environments and to authenticate against our platform.

Following the Getting a new eSIM guide you can learn how to get your eSIM through the API and install it on a compatible device with just a couple lines of code.

An API client application outside the context of an end customer, which resells 1GLOBAL connectivity. This role is restricted to connectivity related operations like listing available products, submitting new orders and checking sim subscription/usage data. Clients with a RESELLER role will typically use the API to connectivity store/management pages in contexts not exclusive to connectivity.

Entitled API resources:

• order
• products
• sim
• subscriptions
• notifications

An API client application, which can authenticate on behalf of an end customer, This role allows the application to manage connectivity and customer related data. Clients with an ACCOUNT_MANAGER role typically will develop applications where users can purchase connectivity and register their accounts with 1GLOBAL, for managing their profile information like email, name, billing address etc.

Entitled API resources:

• order
• products
• sim
• subscriptions
• customer
• notifications

1GLOBAL strives to implement best of breed security controls to its products and services. 1GLOBAL Connect API has considered security by design since its conception. This ensures that all layers from servers to data and source code follow a security by design approach.

1GLOBAL ensures all servers running Connect have a secure architecture and are securely hardened with configurations aligned with international and recognized standards.

Additionally, 1GLOBAL implements a strict vulnerability management program that continuously monitors for potential attack vectors along with the execution of periodic penetration tests to test our defences.

Knowing that preventive controls are just a part of the security puzzle, 1GLOBAL also operates a continuous monitoring and security incident response capability, within from our Cyber Defence Centre.

1GLOBAL Connect is a platform that enables our partners to tap into 1GLOBAL's technology and global network with just a couple of lines of code.

The product includes a set of APIs designed for server-to-server integration, accessible over the internet, that enable a partner to sell 1GLOBAL eSIM based cellular connectivity to their end customers. The product also optionally includes SDKs (software development kits for iOS and Android) to install an eSIM without needing a QR code (get in touch with your 1GLOBAL contact to learn more about these).

Here are some example use-cases that 1GLOBAL Connect can help our partners launch:

• Sell a data plan to an end customer via a partner website
• Sell a data plan to an end customer through a partner App
• Sell a data plan to an end customer through a data marketplace
• Possibility of bundling connectivity as part of another package that the end customer may be purchasing from the partner (e.g. a subscription service)
• Partner can offer employees the option to top-up the data allowance on a corporate mobile device for non-business use

The data plans available via the Connect API are 1GLOBAL data plans. They utilize 1GLOBAL’s global mobile network. The data plans are “data” only.

The 1GLOBAL Connect API uses OAuth2 Client Credentials authentication type to authenticate request. You can get authentication tokens using the following url: https://services.truphone.com/auth/realms/tru-staff/protocol/openid-connect/token. Please be aware that these tokens have a limited duration so you need to include refresh logic in the client code, so that the token gets refreshed automatically without breaking the user experience.

Example using Postman

• Create a new request
• In the Authorization tab, set type to OAuth 2.0
• Fill in the Configure New Token form with the following values:
  • Grant Type: Client Credentials
  • Access Token URL: https://services.truphone.com/auth/realms/tru-staff/protocol/openid-connect/token
  • Client ID: clientID
  • Client secret: clientSecret
  • Scope: profile (only required for Postman)
• Click on the Get New Access Token button, which will trigger a popup saying 'Authentication complete'.
• In the Manage Access Tokens popup, hit the Use Token
• Proceed with your request. The generated token should be valid for 5 minutes

Example using cURL

$ export ACCESS_TOKEN=`curl -s --data \
    "grant_type=client_credentials&client_id=truphone&client_secret=xxxxxx-xxxx-43f3-9fba-85686d72c1c0" \
    https://services.truphone.com/auth/realms/tru-staff/protocol/openid-connect/token \
    | sed 's/.*access_token":"\([^"]*\).*/\1/'`

$ echo $ACCESS_TOKEN        # view the access token

$ curl -H "Authorization: Bearer $ACCESS_TOKEN" https://services.truphone.com/connect-api/...

To refresh the access token, you can use the refresh token. The refresh token is obtained on the first call to obtain the access token (described previously). After that you can use it as shown on the following example:

Example using cURL

$ export ACCESS_TOKEN=`curl -s --data \
    "grant_type=refresh_token&refresh_token=<your_refresh_token>k&client_id=truphone&client_secret=xxxxxx-xxxx-43f3-9fba-85686d72c1c0" \
    https://services.truphone.com/auth/realms/tru-staff/protocol/openid-connect/token \
    | sed 's/.*access_token":"\([^"]*\).*/\1/'`

$ echo $ACCESS_TOKEN        # view the access token

This call will give you an access token and a refresh token. The refresh token will be valid for 30 minutes.

1GLOBAL provides a Production and a Pre-Production environment for the Connect API. Usage examples will work for all environments and it will be possible to install profiles and test connectivity on end devices.

Base URL: https://services.truphone.com/connect-api

Base URL: https://services.truphone.com/esim [DEPRECATED]

The main environment. Should only be used for live traffic. Releases on this environment happen on a scheduled basis and will be communicated to partners.

Base URL: https://services.truphone.com/connect-api-preprod

The Pre-Production environment was created to replace the Staging environment. It has production grade support and throughput, but the data will not be shared with the production environment. The main goal is to allow App developers to develop and test integration with the Connect API, as well as to execute connectivity tests. A few considerations to have when using Pre-Production:

• SIM, Subscription and Customer Data is isolated from Production
• The product catalogues are shared between Production and Pre-Production
• Pre-production will still use test sims and the current commercial agreements and rules around resource recycling will be kept
• In order to access the pre-production environment, you can use the same credentials as for production
• Resources are Recycled in order to optimise usage and reduce storage needs of the environment. As such, every day at 4am GMT the system will clean all resources which have not been used for 24 hours.

Standards and conventions shared by all endpoints

• X-Correlation-ID: In order to easily identify a request on all of 1GLOBAL's subsystems, we require that requesters create a unique identifier that will be sent on every request headers when (X-Correlation-ID) using the api. This way we can easily identify a request or a sequence of events between both 1GLOBAL and the requester.

Dates in requests and responses are treated and stored in the UTC timezone.

All errors thrown by 1GLOBAL Connect API use the same data model in order to facilitate error handling:

{
  "type": "ERROR_TYPE",
  "messages": [
    "error_message_1",
    "error_message_2",
    "..."
  ]
}

Shared error types

Common error types, shared by all endpoints

• INVALID_HTTP_MESSAGE (400) - Parsing of the HTTP request has failed. Usually there's a syntax error in either the JSON body or one of the JSON fields such as dates.
• INVALID_REQUEST_PARAMS (400) - Request was parsed successfully but it contains semantic errors like missing required fields or invalid content like non existing currencies or countries.
• UNAUTHORISED (401) - OAuth2 token is missing or is invalid.
• ACCESS_DENIED (403) - Client is trying to access a resource that it doesn't own like eSIM profiles or customer accounts from other clients.
• INTERNAL_ERROR (500) - Something went wrong with the request and the API can't recover. These should not happen on normal circumstances, and partners are advised to report back to 1GLOBAL, with the correlation id that generated such error.

In some use-cases customers might order an eSIM without realising that either 1) their device doesn't have eSIM support, or 2) the device is locked to a carrier and therefore it will not be possible to install an eSIM profile from 1GLOBAL. In these scenarios it should be possible to revert the order without any cost for our partners and enable a refund to the end customer.

Connect supports the above use-case using the delete SIM API. This endpoint will cancel the eSIM profile and its respective subscriptions provided two conditions:

• The eSIM profile is not installed in any device when the cancellation is triggered
• There was no data usage on the given eSIM profile

If those two conditions are met the resources are freed.

Example Request

curl -X DELETE \
  https://services.truphone.com/connect-api/v1/sim/8944478600000205337 \
   -H "Authorization: Bearer $ACCESS_TOKEN" \
   -H 'Cache-Control: no-cache' \
   -H 'Content-Type: application/json' \
   -H 'X-Correlation-ID: unique-id-from-requester-123'

Example Response

204 No Content

To check the balance of a given subscription the SIM Subscriptions endpoint can be called in order to get the complete list of subscriptions in that SIM. All subscriptions that were ever used in the SIM are returned in the response and it's up to the client code to filter for active subscriptions in order to calculate the balance.

Example Request

curl -X GET \
  https://services.truphone.com/connect-api/v1/sim/8944474600000109299/subscriptions \
   -H "Authorization: Bearer $ACCESS_TOKEN" \
   -H 'Cache-Control: no-cache' \
   -H 'Content-Type: application/json' \
   -H 'X-Correlation-ID: unique-id-from-requester-123'

Example Response

[
  {
    "status": "DEPLETED",
    "id": "Njc1NzY1NzY1ZDIK",
    "initialBalance": "314572800",
    "spentBalance": "314572800",
    "activationDate": "2019-08-01T09:09:33Z",
    "expirationDate": "2019-08-02T09:09:33Z",
    "createdDate": "2020-03-19T15:51:41Z",
    "product": {
      "id": "MzA5MjE3ODMwOTEyCg==",
      "name": "Prepaid data 30GB",
      "period": 0,
      "period_unit": "DAYS",
      "plan_id": "1GLOBALinternalPlan_Id"
    },
    "iccid": "8944474600000109299",
    "device_id": "12345657",
    "auto_renew": "false"
  }
]

If a user wants to check the orders that he/she has submitted, it can be done by invoking the API. Below is an example of the request and a response, as well as a table with all the filters that can be applied

Example Request

curl -X GET \
  https://services.truphone.com/connect-api/v1/order \
   -H "Authorization: Bearer $ACCESS_TOKEN" \
   -H 'Cache-Control: no-cache' \
   -H 'Content-Type: application/json' \
   -H 'X-Correlation-ID: unique-id-from-requester-123'

Example Response

[
    {
      "output": {
        "matchingId": "5C-M1OIY-QHWKD1",
        "iccid": "8944478600000205337",
        "smdpUrl": "rsp.truphone.com",
        "lpa_url": "LPA:1$%rsp.truphone.com$%5C-M1OIY-QHWKD1",
        "subscription_id": "a-5gVXH2sjvICL7U5roet1hMC35UYSCCi4Mbiszdceo="
      },
      "status": "COMPLETED",
      "externalId": "b27ec0e7-ad36-45ab-8e2f-c291441a2355",
      "id": "b27ec0e7-ad36-45ab-8e2f-c291441a2355"
    },
    {
      "status": "ACCEPTED",
      "externalId": "e7897593-ac1a-472f-a847-cad8a9e5171c",
      "id": "e7897593-ac1a-472f-a847-cad8a9e5171c"
    }
]

Browse the catalogue of products available for purchase

View and Create new SIM or subscription orders

View and manage active SIM cards/profiles

View and manage purchased subscriptions