SORACOM Developers

Documents

SORACOM API Usage Guide

In this section we describe the details you need to make use of the SORACOM API.

Terms explained

We begin by explaining the terms you will need to understand in order to properly use the SORACOM API.

On the SORACOM platform, SIMs managed via the API are referred to as Subscribers. Accounts administrating Subscribers are referred to as Operators.

The account used to log in to the SORACOM User Console is an Operator.

Operators maintain multiple Subscribers.

The terms Operator and Subscriber are drawn from the world of telecommunications.

When Subscribers are managed together as one unit, the unit is referred to as a Group. Subscribers can belong to up to a maximum of one group. (Which group they belong to does not matter.)

By putting Subscribers together in a Group, you can bulk edit their settings, such as giving them all the same destination address for SORACOM Beam.

API Keys and API Tokens

The majority of the SORACOM APIs require an API Key and an API Token to call the API.

The API Key is a unique key used to identify an Operator. It is used to, for example, restrict the number of times an Operator can call the API in a given period of time. You should protect the API Key and ensure that it is not known by others.

The API Token is a unique key used to identify a session generated by the API. Each time a new API session is commenced, an API Token must be obtained. API Tokens have an expiration date and will be rendered unusable after that point. You can call the API to issue a new API Token before the expiration date on your current one expires, allowing you to continue your session.

If an API Token reaches its expiration date, you must initiate authentication again and obtain a new API Token.

When obtaining an API Token, you can specify its expiration date. By default, the expiration date is 24 hours. A maximum of 48 hours can be set.

Once an API Token expires, it cannot be used again. This functionality can be used to create short time-delimited tokens to limit the potential risk in the event of a leak. However, a short expiration date affects usability, so the user should select an optimum setting that matches actual needs.

For example, scripts that call the API once when launched and terminate a few seconds later would only need, even with a generous estimate, an expiration date of a minute, while processes involving human interaction with a GUI application could be set to expire after 30-60 minutes of non-interaction.

When calling the SORACOM API, an API Key and API Token are needed. There are only two situations where the above are not required:

API users must first enter an e-mail address and password to authenticate and then receive and API Key and API Token.

Coverage types

The SORACOM platform introduces the notion of coverage type mainly due to the difference of areas where SIM card can be used.

Currently there are two coverage types:

  1. Coverage type: Global

    SIM cards for this coverage type are available in more than 120 countries and regions around the world.    Private connection services such as Canal / Direct / Door / Gate are going to be connected at AWS Frankfurt region (eu-central-1) (rendezvous point = Frankfurt).    Origins of connection for Beam / Funnel are also AWS Frankfurt Region.

  2. Coverage type: Japan

    It is a coverage type that can be used by SIM cards provided from the beginning of SORACOM Air’s service in Japan.    SIM cards for this coverage type available only in Japan. Private connection services such as Canal / Direct / Door / Gate are going to be connected at AWS Tokyo region (ap - northeast 1) (rendezvous point = Tokyo). Origins of connection for Beam / Funnel are also AWS Tokyo region.

Since there is a separate API endpoint for each coverage type, please use the appropriate API endpoint for the corresponding coverage type.

It is possible to authenticate with both API endpoints.

In addition, API key and token obtained by successful authentication can be used for either endpoint.

That is, you can authenticate on either endpoint, even if you do not know in advance which coverage type the account you want to call API corresponds to.

You can also check the contents of API Token obtained as a result of authentication and check the corresponding coverage type.

The coverage type is included as Private claim operator.coverageType in Payload of API Token (JWT format).

For details on how to retrieve the coverage type from API Token in JavaScript, see the following code example.

// `token` contains the API Token that was included in the response from /v1/auth API
var parts = token.split('.');
var claims = JSON.parse(atob(unescape(encodeURIComponent(parts[1]))));
console.log(claims.operator.coverageTypes);
# => ["jp","g"]

(Note: Verify signature of the API Token before using it. Handle errors appropriately)

operator.coverageTypes contains an array of strings as in the example above. If “g” is included, that account is enabled for the coverage type Global. If “jp” is included, that account is enabled for the coverage type Japan.

Date and timestamps

All of the dates and times used in the SORACOM API are treated based on UTC (Coordinated Universal Time).

While there are areas where UNIX Time (time elapsed since January 1, 1970) and YYYYMMDD denominated strings are used, UTC can also be used in these cases.

In other words, if you want to render the date and time of October 1, 12:00 AM JST (Japan Time), you must set it as September 30, 3PM UTC.

For ease of use, the User Console displays the date and time in JST, so the API may seem to be based on JST, but note that it is in fact based on UTC.

Error message format

When an error occurs, the SORACOM API utilizes a unified format to return error messages. (excludes error messages returned in select areas, such as the load balancer before entering the API server.)

{
    "code": "ABC1234",
    "message": "Description of the error"
}

code is the identifying code assigned to the error in question. When contacting support, conveying this code will make identifying the problem area faster.

Including X-Soracom-Lang: in the API request headers will cause the error message to be rendered in the language given, provided that that language is supported. (If unsupported, falls back to English.)

We currently support English (en) and Japanese (ja).

Example: calling the API

As described in the API Keys/API Tokens section, the majority of SORACOM APIs require an API Key and API Token.

First call the API in /v1/auth and perform password authentication to poll the API Key and API Token.

curl  -X POST \
      -H 'Content-Type: application/json' \
      -d '{ "email": "email@example.com", "password": "superStrongP@ssw0rd" }' \
      https://g.api.soracom.io/v1/auth

# Response:
# 200 OK
#
# {
#   "apiKey": "API Key - Random string",
#   "operatorId": "10-character string starting with OP",
#   "token": "API Token - Extremely long random string"
# }

The apiKey and token obtained here will be later used to call the API, so store them in a safe location for later use. (Ideally, they should be stored in volatile memory in an access-restricted location. Authentication allows for the obtaining of the API Key and API Token, so, generally speaking, there is no need to store them permanently client-side.)

Next, call the API from /v1/subscribers and poll the Subscriber index. Specify the previously polled API Key and API Token in the corresponding X-Soracom-API-Key and X-Soracom-Token headers and send them.

curl  -X GET \
      -H "X-Soracom-API-Key: The API Key previously obtained" \
      -H "X-Soracom-Token: The Token previously obtained" \
      https://g.api.soracom.io/v1/subscribers

# Response:
# 200 OK
#
# [
#   {
#     "imsi": "29510xxxxxxxxxx",
#     "msisdn": "42379xxxxxxxx",
#       :
#   },
#   :
# ]

If at least one Subscriber is registered for the Operator, an index of Subscribers should, as above, be obtainable in JSON format.

Use the IMSI (International Mobile Subscriber Identity – the SIM’s ID) in the JSON to try changing the SIM’s speed class.

curl  -X POST \
      -H "X-Soracom-API-Key: The API Key previously obtained" \
      -H "X-Soracom-Token: The Token previously obtained" \
      -H 'Content-Type: application/json' \
      -d '{"speedClass":"s1.fast"}' \
      https://g.api.soracom.io/v1/subscribers/29510xxxxxxxxxx/update_speed_class

# Response:
# 200 OK
#
# {
#   "imsi": "29510xxxxxxxxxx",
#   "msisdn": "42379xxxxxxxx",
#      :
#   "speedClass": "s1.fast",
#      :
# }

How did that go? Were you able to control the SIM through the API? SORACOM offers a range of other APIs, so we encourage you to have a look at the API Reference.

Getting Started

SORACOM Air for Cellular

SORACOM Air for Sigfox

SORACOM Beam

SORACOM Canal/Direct/Door

SORACOM Endorse

SORACOM Funnel

SORACOM Gate

SORACOM Harvest

SORACOM Inventory

SORACOM Junction

SORACOM Krypton

SORACOM Lagoon

Service Detail

Developer Tools

pagetop