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 maintain consistency with telecommunications industry standards, the following terms are used:

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, however; please note 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:auth API method (used to generate an API Key and Token) and Auth:issuePasswordResetToken (used to reset an Operator password), all API methods require an API Key and Token.

API Key and Token pairs are generated when you authenticate as a root user or SAM User. Soracom provides the following authentication methods:

The API Key and Token will allow programmatic API access to your root user and SAM Users.

Handle API Keys and Tokens securely. Never expose them in logs, public repositories, or client-side applications.

Generating an API Key and Token with an ID and Password

To access the Soracom API, users must authenticate using an API Key and Token. One authentication method is to use an ID and Password, which allows root users and SAM Users to obtain credentials for API access.

This method involves sending a request to the Auth:auth API endpoint with the required credentials. If Multi-Factor Authentication (MFA) is enabled on your Soracom account, an additional one-time password (OTP) will be required. Upon successful authentication, the API returns an API Key and Token, which can then be used to make further API requests.

This section provides step-by-step instructions on generating an API Key and Token using an ID and Password for both root users and SAM Users.

For a Root User

Requirements:

An OTP value is also required if the MFA feature is enabled for the root user.

See Multi-Factor Authentication for more information on MFA.

To generate an API Key and Token:

To authenticate, call the Auth:auth API using one of the following methods. For further details on this API endpoint, see the Auth:auth API documentation.

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

Example of a succesful response:

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

To generate an API Key and Token with an OTP:

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

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

See the Examples section for a reference on calling APIs using an API Key and Token.

For a SAM User

A SAM (Soracom Access Management) User is a user account that allows organizations to grant controlled access to their Soracom account without sharing the credentials of the root user. SAM Users are created and managed under Users & Roles in the Soracom User Console.

Requirements:

To create create a password for the SAM User, refer to Authentication Methods for more information.

Note that you can add Inline Permissions to grant the SAM User access to specific APIs.

An OTP value is required if the MFA feature is enabled for the SAM User.

To generate an API Key and Token:

curl -X POST https://g.api.soracom.io/v1/auth \
|  -H 'Content-Type: application/json' \
|  -d '{
|        "operatorId": "OPXXXXXXXXXX",
|        "userName": "my-sam-user",
|        "password": "my$ecretP@ssw0rd"
|      }'

Example of a successful response:

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

To generate an API Key and Token with an OTP:

curl -X POST https://g.api.soracom.io/v1/auth \
|  -H 'Content-Type: application/json' \
|  -d '{
|        "operatorId": "OPXXXXXXXXXX",
|        "userName": "my-sam-user",
|        "password": "my$ecretP@ssw0rd",
|        "mfaOTPCode": "XXXXXX"
|      }'

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

See the Examples section for a reference on calling APIs using an API Key and Token.

Generating an API Key and Token with an AuthKey ID and AuthKey Secret

Use an AuthKey ID and AuthKey Secret for API authentication without an email or password. Generate them in the User Console, then use them to obtain an API Key and Token for secure API access.

Requirements:

To generate an API Key and Token:

  1. Generate the AuthKey ID and AuthKey Secret from the User Console.

  2. Generate an API Key and Token.

    curl -X POST https://g.api.soracom.io/v1/auth \
|  -H 'Content-Type: application/json' \
|  -d '{
|        "authKeyId": "keyId-XXXXXXXXXXXXXXXXXXXXXXXXX",
|        "authKey": "secret-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
|      }'

    Note that authkeyID refers to AuthKey ID and authKey refers to AuthKey Secret.

    Example of a succesful response:

    {
  "operatorId": "OP0012345678",
  "apiKey": "keyId-XXXXXXXXXXXXXXXXXXXXXXXXX",
  "token": "<MY-TOKEN>"
}

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

See the Examples section for a reference on calling APIs using an API Key and Token.

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 plan-US-max plan-US-NA
planP1 planX1 planX2 planX3 planX3-EU 		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 to obtain an 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.

The following JavaScript code retrieves 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 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 off and so on. The last_evaluated_key is provided as part of the output of the link header of the previous call.

To retrieve a list of SIMs, use the following /listSims query:

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

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 \
|  -H "X-Soracom-API-Key: $X_SORACOM_API_KEY" \
|  -H "X-Soracom-Token: $X_SORACOM_TOKEN"
|  https://g.api.soracom.io/v1/sims?last_evaluated_key=1234567890123456780

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

Retrieve a List of Subscribers

Use the /subscribers method to retrieve the list of subscribers in the account:

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's Speed Class

To update a subscriber's speed class, use the following /update_speed_class request with the subscriber's IMSI:

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

Response (200 OK):

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

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