Developer Tools

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

• You must have a production Soracom account (hereafter referred to as "production account").

Precautions

• Certain API methods, such as Event Handler, may not activate or perform actions due to differences between the sandbox and production environments.
• Configurations and other data stored in the Sandbox are not guaranteed to persist. Databases associated with the Sandbox environment may be cleaned at any time without notice.
• Similarly, when developing with CI (continuous integration) tools, ensure that any necessary environmental configuration has been set up prior to running tests, as they may have been previously removed.
• The sandbox environment is provided on a best-effort, as-is basis, and may become temporarily unavailable for maintenance or upgrades without notice.
• Soracom support is happy to answer questions regarding Sandbox usage, however support priority will be given to production environments.

---

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.

---

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

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.

---

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
  }
]