Getting started with Kore Wireless Connectivity API

This article covers the basics to start using the Kore Wireless Connectivity API, I hope this guide helps you onboard the API faster!

Hi there, my name is Vitor Ribeiro; I am a Solutions Architect at Kore Wireless.

Part of my job includes onboarding customers on our Developer Portal for our Connectivity API. This article covers some of the frequently asked questions related to our Connectivity API and how to get started.

Version en Español aqui.

Prerequisites

You can view the Developer Portal API documentation, but to view and manage your API keys, you must be contracted for Kore Wireless ConnectivityPro™. Otherwise, you won’t be able to see the Authentication endpoint described below.

If you are not a Kore Wireless customer and are interested in our services, contact us here.

You don’t need to be a software developer but must be familiar with what a REST API is; AWS has this article on REST API that can give you enough insight to understand this article. For my API calls, I used PostMan, you can view their 101 videos on their website, this webinar gives you enough insight to understand this article.

Overview

The Developer Portal is a public web page for customers, partners, and builders to integrate and leverage Kore Wireless Services through APIs.

The Developer Portal enabled Kore Wireless to have a single point to manage all of your Kore Wireless APIs; this is referred to as KORE One^™.

Today we offer the following APIs under the Developer Portal:

• AMS - If you are contracted for Deployment Services (Forward & Reverse Logistics), this is used to place new orders, service exchange, transfer orders, and view orders.

• Connected Health - If you are contracted for Connected Health Telemetry Solution, this API helps users manage their studies/deployment through APIs.

• Connectivity - If you are contracted for ConnectivityPro™, this API helps you manage your SIM subscriptions.

• Fleet Management - If you are contracted for Position Logic, this API helps you manage your Telematics Fleet.

• Streaming - If you are contracted for ConnectivityPro™, this API helps you manage your SIM subscriptions.

This article will cover the Connectivity API, so you can manage your SIMs subscriptions via API.

Why use Kore’s API?

If you are using Verizon or ATT for example, your development team would need to implement two different APIs, that use two different endpoints, different sets of endpoints for different features, etc.

With Kore Wireless, you write your code against ONE API endpoint, and from that point forward, all service types available on your contract are also available to you.

Introduction

Creating a Client

Once you have access to your Developer Portal, please follow the getting started to set up your first client, once you have a client created, selecting it, will enable you to view your Production API keys and your Sandbox API keys.

Getting an Authentication Token

Source: https://developer.korewireless.com/getting-started?id=2.1.1.3

KORE uses the OAuth workflow, specifically the Client Credentials Workflow. When you create a client, your client’s access is also created through Client ID, Client Secret, and API Key. Keep all this information secret as these pieces of information are used to authenticate your client to access your organization's information.

• Client ID is the unique identifier of your application.

• Client Secret is the key that you pass in for secure calls to KORE’s APIs.

• API Key is how KORE allows clients from APIs.

See below for a high-level overview.

Using Postman, set up a POST request to https://api.korewireless.com/Api/api/token for Production or for Sandbox. Your set of keys determines which authentication token you will get, for Production or Sandbox.

The body of your request must include:

• The key “grant_type” key with a value of “client_credentials”.

• The key “client_id” key with a value from the Developer Portal.

• The key “client_secret” key with a value from the Developer Portal.

You can also use cURL to get an authentication token, use the example below to perform a request.

curl -L -X POST "https://api.korewireless.com/Api/api/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=[REPLACE_WITH_YOUR_INFO]" -d "client_secret=[REPLACE_WITH_YOUR_INFO]"

Here’s what the cURL returns:

The authentication Token is valid for 10 hours, after 10 hours, you will need to call the authentication endpoint again for a new token.

Getting the account-id

Most endpoints from the Connectivity API will require the “account-id” as part of the required fields; obtaining your “account-id” is essential to interface with Kore’s Connectivity API.

Using Postman, setup a GET request to https://api.korewireless.com/connectivity/v1/accounts?email=<YOUR_EMAIL> for Production or to https://sandbox.api.korewireless.com/connectivity/v1/accounts?email=<YOUR_EMAIL> for Sandbox.

Your GET request must include:

• The key “email” with a value from the Developer Portal.

• A valid Authentication token

• x-api-key as part of your headers

Getting the activation-profile-id

Using Postman, setup a GET request to https://api.korewireless.com/connectivity/v1/accounts/{account-id}/activation-profiles for Production

or

https://sandbox.api.korewireless.com/connectivity/v1/accounts/{account-id}/activation-profiles for Sandbox.

Your GET request must include:

• The key “account-id” with a value from your previous call

• A valid Authentication token

• x-api-key as part of your headers

Managing your SIM subscriptions

Requesting details about a subscription

Using Postman, setup a GET request to https://api.korewireless.com/connectivity/v1/accounts/{account-id}/subscriptions for Production or https://sandbox.api.korewireless.com/connectivity/v1/accounts/{account-id}/subscriptions for Sandbox.

Your GET request must include:

• The key “account-id” with a value from your previous call

• A valid Authentication token

• x-api-key as part of your headers

• A query-string parameter, in my example, I will use the EID found on my plastic.

Activation

Using Postman, setup a POST request to https://api.korewireless.com/connectivity/v1/accounts/{account-id}/provisioning-requests/activate for Production or https://sandbox.api.korewireless.com/connectivity/v1/accounts/{account-id}/provisioning-requests/activate for Sandbox.

Your POST request must include:

• The key “account-id” with a value from your previous call

• A valid Authentication token

• x-api-key as part of your headers

• A body containing the Activate schema

In this example, my subscription state is set to STOCK, which is the default state once you place an order and sims are available on your account.

I want to set my state as test state, this state allows a customer to perform a device/sim validation test while in the production line without turning the subscription into a billable item.

{
  "activate": {
    "activation-profile-id": "<YOUR_ACTIVATION_PROFILE>",
    "activation-state": "test",
    "subscriptions": [
      {
        "subscription-id": "<YOUR_SUBSCRIPTION_ID>"        
      }
    ]
  }
}

You will be given 3 thresholds for a subscription, a data usage threshold, an SMS usage threshold, and a time threshold. Whichever it is triggered first, set the state to Active - billable. These terms are defined in your contract, you can discuss this with your Account Rep.

For more information on States, read this article.

Response Sample:

{
    "status": "success",
    "data": {
        "provisioning-request-id": "cmp-cpro-request-9591174",
        "message": "Your request has been acknowledged"
    }
}

Considerations

This article covered how to get an Authentication Token, how to obtain the account-id, how to get the activation-profile-id, how to get subscription-id, and how to activate a SIM.

As shown, it is important that your headers include your x-api-key, a valid auth token, and an account-id.

For activation, you must have your subscription-id first and your activation-profile-id.

If you have any questions, don’t hesitate to reach out to me here.

Available Resources

Postman Collection

Kore offers a Postman collection that enables you to validate the APIs without writing any code, alternatively, the Developer Portal documentation also includes the ability to call the endpoints, you must be logged into the Developer Portal to view this Auth Section.

Github

Kore Wireless has a GitHub repository containing code samples. You can view code samples related to the Connectivity API here.