Soracom API Sandbox Usage Guide

In some cases, you may want to test Soracom API functionality in a test or development environment before using the API in a production environment. The Soracom API Sandbox allows you to make API calls without altering subscribers in your production environment, in order to to test and verify API behavior.

As the API Sandbox is based on the Soracom API, please ensure that you have read through the API Usage Guide in advance.

For a list of sandbox-specific API endpoints, refer to the API Sandbox Reference documentation.

Requirements

Precautions


API Sandbox Usage

To setup the API sandbox, we need to:

  1. Create a SAM User in our production account
  2. Create a new sandbox Operator account in the sandbox environment
  3. Register dummy SIMs in the sandbox account

Create a SAM User

A Soracom Access Management (SAM) User is required for generating an AuthKey in order to create of a sandbox environment. However, The SAM User itself does not require any special permissions, and we recommend creating a SAM User without any special permissions in order to prevent unwanted usage.

First, follow the instructions on Create a SAM user to generate a certificate key.

  1. Login to your production account.

  2. Click your account menu, then select Security.

  3. Click the Create a user button, and enter a username.

  4. Your new SAM User will appear in the list of users. Click it to open its details.

  5. Click the Authentication tab, then click Generate an AuthKey. A dialog will appear with an AuthKey ID and AuthKey Secret. Copy these values to a safe location.

    The AuthKey Secret will only be shown once. If you have lost the Secret, you must generate a new AuthKey.

Now that you have create a SAM User with an AuthKey, you can set up a sandbox Operator account.

Although sandbox environmented are cleaned periodically, the SAM User and its AuthKey will remain in your production account. When setting up a new sandbox Operator account, you can re-use the AuthKey without having to create a new SAM User each time.


Create a Sandbox Operator Account

Creating a sandbox Operator account is done by the /sandbox/init API. Here, we will provide the AuthKey ID and Secret generated earlier, and create a new Operator account with sandbox email and password credentials of our choice:

curl -X POST \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "authKeyId": "<MY-AUTHKEY-ID>",
>        "authKey": "<MY-AUTHKEY-SECRET>",
>        "email": "sandbox@soracom.io",
>        "password": "my$ecretP@ssw0rd"
>      }' \
>  https://api-sandbox.soracom.io/v1/sandbox/init

Response (201 Created):

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

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.

curl -X POST \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "authKeyId": "<MY-AUTHKEY-ID>",
>        "authKey": "<MY-AUTHKEY-SECRET>"
>      }' \
>  https://api-sandbox.soracom.io/v1/auth

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

To avoid account creation errors, use a different email address each time you setup a sandbox account. Some email providers, such as Gmail (including Google Apps for Work), allow you to add arbitrary text to your email address using a + sign, such as myemail+soracomtest@gmail.com, while still receiving email in your normal account.

Since the API call was successful, we can now use the API Key and Token from the response to make API calls within the sandbox account.

In a production account, a payment method must be registered prior to accessing Soracom services. When creating a sandbox account, dummy payment information is automatically registered, so there is no need to register a payment method separately.


Register Dummy SIMs

As many API methods require the presence of a subscriber, we'll need to populate our sandbox account with some SIMs. Rather than registering a real SIM, we can generate a subscriber using the /sandbox/subscribers/create method:

curl -X POST https://api-sandbox.soracom.io/v1/sandbox/subscribers/create

Response (200 OK):

{
  "imsi": "<GENERATED-IMSI>",
  "registrationSecret": "<GENERATED-PASSCODE>",
  //...
}

We can now use the generated IMSI and Passcode to register the subscriber to our sandbox account, just as we would register an actual SIM to a production account:

curl -X POST \
>  -H 'X-Soracom-API-Key: <MY-SANDBOX-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-SANDBOX-TOKEN>' \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "registrationSecret": "<GENERATED-PASSCODE>"
>      }' \
>  https://api-sandbox.soracom.io/v1/subscribers/<GENERATED-IMSI>/register

Response (200 OK):

{
  "imsi": "<GENERATED-IMSI>",
  "iccid": "<GENERATED-ICCID>",
  "msisdn": "<GENERATED-MSISDN>",
  //... other subscriber details
}

We can repeat this process as many times as we'd like, for the number of subscribers we want to test.


Sandbox Testing

Now that we have set up our sandbox account and added some dummy SIMs, we can test API behavior just as if we were using the production API.

Get a List of Subscribers

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

Response (200 OK):

[
  {
    "imsi": "001010012345678",
    "msisdn": "990012345678",
    "ipAddress": "10.0.0.123",
    "operatorId": "OP0012345678",
    "apn": "soracom-sandbox.io",
    "type": "s1.standard",
    //... additional subscriber details
  }
]