Soracom API Usage Guide

Overview

The Soracom API lets you easily integrate Soracom management features and services into your IoT application using conventional HTTP requests.

Terminology

To remain consistent with terminology in the telecommunications industry, you will often see the following terminology in use:

In practice, an Operator may administer multiple Subscribers, while each Subscriber belongs to only one Operator.

Depending on your organizational requirements, you may have multiple Operators (Soracom accounts), however please keep in mind that there are restrictions with transferring Subscribers between Operators.

In addition, multiple Subcribers can be managed together by adding them to a Group. Groups can then be used to configure settings for multiple Subscribers at the same time. There is no limit to the number of Groups you can create, however a Subscriber can only belong to one Group at a time, and both the Subscriber and Group must be administered by the same Operator (in other words, you cannot assign a Subscriber to another Operator's group).


Generating an API Key and Token

When using the Soracom API, authorization is provided by an API Key and Token. Except for the auth API method (used to generate an API Key and Token) and issuePasswordResetToken (used to reset Operator password), all API methods require an API Key and Token.

API Key and Token pairs are generated by authenticating your Operator account. Soracom provides the following authentication methods:

The API Key and Token will uniquely identify your Operator account. Because the API Key and Token will allow programmatic access to your Soracom account, you should take care to protect them so they are not discovered by an unauthorized party.


Token Timeout

To reduce any potential security risk, each API Key and Token pair is effective for only temporary period, known as its TTL. After an API Key and Token pair expires, it cannot be used again. Once an API Key and Token pair expire, simply call the auth API method again to receive a new pair.

By default, the TTL of an API Key and Token pair is 86,400 seconds (24 hours).

When implementing the Soracom API into your application, we recommend specifying a TTL that matches your application requirements. For example, for applications where a device only needs to send a small amount of data, a TTL of a few minutes is typically adequate. In other applications where human interaction or input is required, a longer TTL of 30-60 minutes may be appropriate. Setting an API Key and Token pair TTL that matches your application requirements will further reduce any security risk.

When generating an API Key and Token pair, a minimum of 180 seconds (3 minutes) and a maximum of 172,800 seconds (48 hours) can be set for the TTL.


Coverage Types and API Endpoints

Just as Soracom Air IoT SIMs differ primarily by Global or Japan-only coverage, Soracom API access is also split into two corresponding API endpoints:

Global Japan
SIM Type plan01s plan01s - LDV planP1 planX1 plan-D plan-DU plan-K plan-KM1
API Endpoint

https://g.api.soracom.io

https://api.soracom.io or
https://jp.api.soracom.io

Regardless of your subscriber's region, you can authenticate your Operator account and obtain and API Key and Token from any API endpoint. In addition, an authorized API Key and Token can be used with any API endpoint, regardless of which endpoint was used to generate the pair.

For all other API methods, ensure that you use the endpoint appropriate for your Operator account's coverage type or Subscriber's coverage area.

Checking Coverage Types

In some cases, it may be useful to programmatically check the coverage types (Global and/or Japan) that are available for your Operator account.

When generating an API Key and Token, the Token itself is a JSON Web Token (JWT) which contains information about the coverage types available to your account.

To retrieve the coverage types, parse and decode the Token to get its payload. The payload contains a operator.coverageType key which is an array containing the coverage types available to your Operator account.

For example, the following Javascript code will return the coverage types array:

// "token" contains the string content of the API Token returned from /v1/auth
var parts = token.split('.');
var claims = JSON.parse(atob(unescape(encodeURIComponent(parts[1]))));
console.log(claims.operator.coverageTypes); // ["jp", "g"]

When parsing the API Token, make sure to verify its signature to ensure the Token has not been compromised.


Dates and Timestamps

All of the dates and times used in the Soracom API are based on UTC (Coordinated Universal Time) +00:00.

In some instances, Unix epoch time (seconds elapsed since January 1, 1970) or a date format such as YYYYMMDD are used. These timestamps are also based on UTC +00:00.

When calling an API that requires a date or time input, or when parsing an API response that includes a date or time value, ensure that you convert from your local timestamp to UTC +00:00 (and vice versa).


Error Messages

When an error occurs, the API will return an error message in a unified format.

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

If an error occurs during an API call prior to the request reaching the API server, an error message may not be returned.

When contacting Soracom support in order to troubleshoot API usage, please provide the error code if available.

By default, the message body will appear in English. However, the locale can be controlled by specifying an X-Soracom-Lang header in the API call. Currently the supported error message locales are:


Examples

Generate an API Key and Token

We'll call the /auth API using our Soracom account email and password for authentication:

curl -X POST \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "email": "sora@soracom.io",
>        "password": "my$ecretP@ssw0rd"
>      }' \
>  https://g.api.soracom.io/v1/auth

We should get a 200 OK response, which will return some data:

{
  "operatorId": "OP0012345678",
  "apiKey": "<MY-API-KEY>",
  "token": "<MY-TOKEN>"
}

We can then use <MY-API-KEY> and <MY-TOKEN> to call other parts of the API, ensuring that both are stored in volatile, access-restricted memory so that they remain protected.

Retrieve a List of Subscribers

Let's perform a simple request to see what subscribers are in our account by using the /subscribers method:

curl -X GET \
>  -H "X-Soracom-API-Key: <MY-API-KEY>" \
>  -H "X-Soracom-Token: <MY-TOKEN>" \
>  https://g.api.soracom.io/v1/subscribers

Response (200 OK)

[
  {
    "imsi": "295050012345678",
    //...
  },
  {
    "imsi": "295050012345679",
    //...
  },
  //...
]

Update a Subscriber Speed Class

Now let's use the IMSI of one of our subscribers in order to update its speed class using the /update_speed_class method:

curl -X POST \
>  -H "X-Soracom-API-Key: <MY-API-KEY>" \
>  -H "X-Soracom-Token: <MY-TOKEN>" \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "speedClass": "s1.fast"
>      }' \
>  https://g.api.soracom.io/v1/subscribers/295050012345678/update_speed_class

Response (200 OK):

{
  "imsi": "295050012345678",
  "speedClass": "s1.fast",
  //...
}

For a complete list of API methods available, please refer to the API Reference.