Developer Tools

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 Subscribers 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 a 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 plan-NA1 plan-US planX3 planX3-EU
planP1 planX1 planX2 planX3 plan-US-max plan-US-NA		 plan-D plan-DU plan-K plan-K2 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.

To call the Soracom API the API endpoint must be reachable by the device. Therefore, to call the API from a SIM located inside a Virtual Private Gateway, the VPG's Internet Gateway must be enabled and the Outbound Filter must be disabled.

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).

Rate Limits

The Soracom API sets a maximum number of requests per minute, or a "rate limit", for calls made to the same relational API group.

When you call the API, the following HTTP response headers will be included that provide more information about rate limiting:

HTTP Response Header Explanation
x-soracom-ratelimit-limit The maximum number of times per minute that APIs in the called API's group can be called. The same value will be returned regardless of the number of calls made to this group.
x-soracom-ratelimit-remaining The remaining number of times that APIs in the called API's group can be called this minute. When the maximum number of requests is reached, the value becomes 0 and an HTTP 429 Too Many Requests error will be returned.
x-soracom-ratelimit-seconds-before-refresh The number of seconds remaining until the one minute period elapses and the rate limit is refreshed.

For example, the following APIs belong to the Sim group, and therefore share a rate limit:

Therefore, if the rate limit is exceeded when calling Sim/getSim and an HTTP 429 Too Many Requests error is returned, additional calls to Sim/listSims or Sim/listSimStatusHistoryAPIs will also be rate-limited and return the same HTTP 429 Too Many Requests error. It is recommended to implement an exponential backoff strategy or delay subsequent API calls to avoid further rate limiting.

The limit property is designed to regulate the amount of data received per API call per minute.

For ease of use, Soracom's API Reference page organizes API calls by these relational groups.

While most APIs are limited by group, the following API calls are limited by caller IP address:

Auth

  • Auth/auth
  • Auth/issuePasswordResetToken
  • Auth/verifyPasswordResetToken

Device

  • https://api.soracom.io/v1/devices/{device_id}/publish

Operator

  • Operator/issueMFARevokingToken
  • Operator/verifyMFARevokingToken

Email

  • Email/verifyAddEmailToken

The rate limit is set at a level that is considered acceptable for normal use. If you need a higher rate limit, please contact Soracom support and provide the following information:

  • The API call you would like to increase the limit of.
  • The estimated number of requests per minute required.
  • Details about your use case and why it requires a higher limit.

Our engineering team will then evaluate the possibility of a rate limit increase.

Handling Pagination

For some large API calls, the output is limited to a certain number of return items. Calls like these will also offer the ability to enter a last_evaluated_key so that a second API call can pick up that list where the first left of and so on. This last_evaluated_key will be provided as part of the output of the previous call in the link header.

For example, using the /listSims method we can use the following query.

curl -i -X GET https://g.api.soracom.io/v1/sims \
-H "X-Soracom-API-Key: $X_SORACOM_API_KEY" \
-H "X-Soracom-Token: $X_SORACOM_TOKEN"

Which returns the following headers before the data output.

{
"date": "Tue, 06 Jun 2023 07:04:19 GMT",
"content-type": "application/json",
"cache-control": "no-cache",
"link": "</v1/sims?last_evaluated_key=1234567890123456780>; rel=next",
"vary": "Accept-Encoding",
"x-soracom-next-key": "1234567890123456780",
"x-soracom-ratelimit-limit": "1000",
"x-soracom-ratelimit-remaining": "999",
"x-soracom-ratelimit-seconds-before-refresh": "60",
}

From the link header here we can see that our last_evaluated_key is 1234567890123456780, which can be used in subsequent calls to pick up where the previous list left off. Here is an example of the same /listSims call using that key.

curl -i -X GET https://g.api.soracom.io/v1/sims?last_evaluated_key=1234567890123456780 \
-H "X-Soracom-API-Key: $X_SORACOM_API_KEY" \
-H "X-Soracom-Token: $X_SORACOM_TOKEN"

This will then return additional data and a new last_evaluated_key to continue from the end of the new list if applicable.

{
"date": "Tue, 06 Jun 2023 07:11:25 GMT",
"content-type": "application/json",
"cache-control": "no-cache",
"link": "</v1/sims?last_evaluated_key=1234567890123456781>; rel=next",
"vary": "Accept-Encoding",
"x-soracom-next-key": "1234567890123456781",
"x-soracom-ratelimit-limit": "1000",
"x-soracom-ratelimit-remaining": "998",
"x-soracom-ratelimit-seconds-before-refresh": "46"
}

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.