AuthKeys

While the Soracom User Console provides full access to your Soracom account using a web browser, you may want to perform SIM and device management, service configuration, or other tasks programmatically, such as to deactivate a SIM when a webhook is called, or to configure a SIM during your manufacturing process.

AuthKeys provides a secure mechanism for accessing your Soracom account programmatically using the Soracom API and Soracom CLI tools.

Overview

When logging in to your Soracom account using the web-based User Console, your root account (primary email address and password) or SAM User (Operator ID, username, and password) login information is used to generate a temporary API key and token. This key/token pair is stored in your browser and used to authorize any actions you perform while on the User Console.

An AuthKey provides a similar mechanism for generating this temporary API key and token, which can then be used to call the Soracom API or run the Soracom CLI tool.

Each AuthKey contains a pair of values:

an AuthKey ID which acts as a username
an AuthKey Secret which acts as a password

Using an AuthKey to generate an API key and token ensures that you do not expose your root account or SAM User credentials in your code, and allows you to practice password rotation without affecting any applications that are using an AuthKey.

Although you can also use your root account or SAM User credentials to manually generate an API key and token, we strongly recommend using an AuthKey for security.

Furthermore, unlike your root account or SAM User login information, an AuthKey cannot be used to login to the Soracom User Console, and can be easily revoked and reissued for security or as your application requirements change, without affecting your ability to login to the User Console.

Access Control

Each AuthKey will inherit the permissions assigned to the corresponding credentials:

AuthKeys generated for your root account will be granted full admin access to your Soracom account and can be used to call any Soracom API or execute any Soracom CLI command.
AuthKeys generated for a SAM User will be granted any permissions provided to the SAM User through Default SAM User Permissions settings, Roles attached to the user, or Inline Permissions.

While it is possible to create a SAM User and provide it with full permissions, you can also combine a SAM User with limited permissions together with an AuthKey in order to strictly limit what actions your application is allowed to perform on your Soracom account.

Despite its name, a SAM User does not necessarily need to correspond to an individual in your organization. By creating a SAM User without a password, the user will not be able to access the User Console. However, the SAM User's AuthKey can still be used by your application to generate an API key/token pair and access the Soracom API that have been granted to the user.

For more information on controlling access, refer to the Users and Roles documentation.

Limitations

Your root account is limited to two (2) AuthKeys.
Each SAM User is limited to two (2) AuthKeys. However, you may create as many SAM Users as needed.
If your root account or SAM User already has two (2) AuthKeys, you must first revoke one in order to generate a new AuthKey.
Even if a SAM User is granted full permissions, certain account security APIs (such as resetting the root account password) are only available to the root account for security.

Compared to Credential Sets

An AuthKey is an authentication mechanism that allows an external application (such as a webhook on your backend system) to access your Soracom account and perform actions using the Soracom API or Soracom CLI.

By comparison, a Credential Set is used by Soracom to programmatically interact with or perform actions on an external service or device on your behalf.

Root Account AuthKeys

To generate an AuthKey for your root account:

Login to the User Console. Click your account menu, then select Security.

https://console.soracom.io
From the Security screen, click the AuthKeys tab. Then click the Create an AuthKey button.

https://console.soracom.io
An AuthKey ID and AuthKey Secret key pair will be automatically generated.

Make sure to save the AuthKey Secret as it will not be displayed again.

When generating a new AuthKey, the AuthKey Secret will only be shown once. Ensure that you save the secret key in a secure location. If you lose the secret key, you will need to generate a new AuthKey.

Your new AuthKey will be listed, including information about when it was generated and when it was last used. You can also use this screen to revoke and remove any unused AuthKeys associated with your root account.

SAM User AuthKeys

Access to managing SAM User AuthKeys is limited in the following ways:

When logged in as the Root Account - You can manage AuthKeys for all SAM Users.
When logged in as a SAM User - Access depends on API permissions granted to your SAM User.

Depending on on your SAM User's permissions, you may be able to manage AuthKeys for all SAM Users, for a specific SAM User, or only for your SAM User. The ability to manage AuthKeys can also be disabled (and in turn only be managed by a different SAM User or by the Root Account) in order to prevent an application from using an AuthKey to generate further AuthKeys. Refer to the Users and Roles documentation Permission Statements section for more information.

To generate or revoke an AuthKey for a SAM User:

Login to the User Console. Click your account menu, then select Security.

https://console.soracom.io
From the Security screen, click the Users tab. Then click the name of the SAM User you want to manage.

https://console.soracom.io
From the SAM User settings page, click the Authentication tab. Then from the AuthKeys panel, click the Generate an AuthKey button.

https://console.soracom.io
An AuthKey ID and AuthKey Secret key pair will be automatically generated.

When generating a new AuthKey, the AuthKey Secret will only be shown once. Ensure that you save the secret key in a secure location. If you lose the secret key, you will need to generate a new AuthKey.

Refer to the Users and Roles documentation for more information about SAM User authentication methods.

API Authentication

Soracom API

Accessing the Soracom API with an AuthKey consists of two steps:

Send an HTTP POST request to the /auth API endpoint, including your AuthKey ID and AuthKey Secret in the body of the request as authKeyId and authKey values, respectively. If verified, the API will return a response which contains apiKey and token values.
Include the apiKey and token values in any subsequent API calls as HTTP request headers using the following format:
- X-Soracom-API-Key: <apiKey>
- X-Soracom-Token: <token>

For more details on using the Soracom API, refer to the API Reference Guide documentation.

Examples

#!/bin/bash

# This example uses `jq` to parse JSON responses. Ensure that you have
# installed jq to your system, and that you can run the `jq` command.

AUTH_KEY_ID="keyId-xxxxxxxxxx"
AUTH_KEY="secret-yyyyyyyyyy"

# Soracom API /auth endpoint
#
# First we need to call the auth API to get an API key and token. We need to
# set up an HTTP request with appropriate headers and pass our AuthKeys in as
# the HTTP request body.
body="{
  \"authKeyId\": \"${AUTH_KEY_ID}\",
  \"authKey\": \"${AUTH_KEY}\"
}"

# Create the Soracom API auth HTTP request and store the response. Here we will
# store the HTTP status code in the `auth` variable, and the HTTP response body
# in a file named `response`
auth=$( curl -s -w "%{http_code}" -o response -X POST \
  -H "Content-Type: application/json" \
  -d "${body}" \
  https://g.api.soracom.io/v1/auth )

# If the response contains an error code, log the error and exit
if [ "$auth" != "200" ]; then
  echo "Soracom API auth error: $( cat response )"
  exit 1
fi

# Soracom API /sims endpoint
#
# If our script reaches this point, then the previous HTTP request completed
# successfully. We can now use the `apiKey` and `token` values to call other
# Soracom API endpoints.
apiKey=$( cat response | jq -r .apiKey )
token=$( cat response | jq -r .token )

# Create the Soracom API listSims HTTP request and store the response. We will
# similarly store the HTTP status code in the `sims` variable, and the HTTP
# response body in the `response` file
sims=$( curl -s -w "%{http_code}" -o response -X GET \
  -H "X-Soracom-API-Key: ${apiKey}" \
  -H "X-Soracom-Token: ${token}" \
  https://g.api.soracom.io/v1/sims )

# If the response contains an error code, log the error and exit
if [ "$sims" != "200" ]; then
  echo "Soracom API listSims error: $( cat response )"
  exit 1
fi

# Output the response
cat response

// Use NodeJS's built-in `https` module.
// You can also use `request`, `axios`, or another module instead.
const https = require('https');

// To improve security, get AuthKey ID and Secret from environment variables
// rather than storing them here.
const AUTH_KEY_ID = 'keyId-xxxxxxxxxx';
const AUTH_KEY = 'secret-yyyyyyyyyy';

// Use an async immediately-invoked function expression (IIFE) so that we can
// wait for each Soracom API call to complete.
(async () => {
  try {
    /**
     * Soracom API /auth endpoint
     *
     * First we need to call the auth API to get an API key and token. By
     * wrapping the HTTP request in a promise, we can tell our script to wait
     * before making the next API call. Once this HTTP request completes, our
     * API key and token will be stored in the `auth` variable.
     */
    const auth = await new Promise((resolve, reject) => {
      // Set up the HTTP request options.
      const options = {
        hostname: 'g.api.soracom.io',
        port: 443,
        path: '/v1/auth',
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        }
      };

      // Create the Soracom API auth HTTP request.
      const request = https.request(options, (response) => {
        // Store the body of the response.
        let body = '';
        response.on('data', (data) => {
          body += data;
        });

        response.on('end', () => {
          // If we receive a response other than 200, fail the promise.
          if (response.statusCode != 200) {
            reject(`Soracom API auth error: ${response.statusCode} ${response.statusMessage} (${body})`);
          }

          // Otherwise, complete the promise by returning the response data
          // which will contain `apiKey` and `token` values.
          resolve(JSON.parse(body));
        });
      });

      // Fail the promise if there are any other HTTP request errors.
      request.on('error', (error) => {
        reject(`HTTP request error: ${error.message}`);
      });

      // Write the AuthKey to the body of the HTTP request.
      request.write(JSON.stringify({
        authKeyId: AUTH_KEY_ID,
        authKey: AUTH_KEY
      }));

      request.end();
    });

    /**
     * Soracom API /sims endpoint
     *
     * If our script reaches this point, then the previous HTTP request
     * completed successfully. We can now use the `apiKey` and `token` values
     * to call other Soracom API endpoints.
     */
    const sims = await new Promise((resolve, reject) => {
      // Set up the HTTP request options.
      const options = {
        hostname: 'g.api.soracom.io',
        port: 443,
        path: '/v1/sims',
        method: 'GET',
        headers: {
          'X-Soracom-API-Key': auth.apiKey,
          'X-Soracom-Token': auth.token
        }
      };

      // Create the Soracom API listSims HTTP request.
      const request = https.request(options, (response) => {
        // Store the body of the response.
        let body = '';
        response.on('data', (data) => {
          body += data;
        });

        response.on('end', () => {
          // If we receive a response other than 200, fail the promise.
          if (response.statusCode != 200) {
            reject(`Soracom API listSims error: ${response.statusCode} ${response.statusMessage} (${body})`);
          }

          // Otherwise, complete the promise by returning the response data
          // which will contain our SIM data.
          resolve(JSON.parse(body));
        });
      });

      // Fail the promise if there are any other HTTP request errors.
      request.on('error', (error) => {
        reject(`HTTP request error: ${error.message}`);
      });

      request.end();
    });

    /**
     * Output the response.
     */
    console.log(sims);

  } catch (error) {
    console.log(error);
  }
})();

import requests, json

AUTH_KEY_ID = "keyId-xxxxxxxxxx"
AUTH_KEY = "secret-yyyyyyyyyy"

# Soracom API /auth endpoint
#
# First we need to call the auth API to get an API key and token. We need to
# set up an HTTP request with appropriate headers and pass our AuthKeys in as
# the HTTP request body.
headers = {
  "Content-Type": "application/json"
}
body = {
  "authKeyId": AUTH_KEY_ID,
  "authKey": AUTH_KEY
}

# Create the Soracom API auth HTTP request and store the response.
auth = requests.post("https://g.api.soracom.io/v1/auth", data=json.dumps(body), headers=headers)

# If we receive a response other than 200, log the error and quit.
if auth.status_code != 200:
  print("Soracom API auth error: %s %s" % (auth.status_code, auth.text))
  quit()

# Soracom API /sims endpoint
#
# If our script reaches this point, then the previous HTTP request completed
# successfully. We can now use the `apiKey` and `token` values to call other
# Soracom API endpoints.
headers = {
  "X-Soracom-API-Key": auth.json().get("apiKey"),
  "X-Soracom-Token": auth.json().get("token")
}

# Create the Soracom API listSims HTTP request and store the response.
sims = requests.get("https://g.api.soracom.io/v1/sims", headers=headers)

# If we receive a response other than 200, log the error and quit.
if sims.status_code != 200:
  print("Soracom API listSims error: %s %s" % (sims.status_code, sims.text))
  quit()

# Output the response.
print(sims.json())

Soracom CLI

To configure the Soracom CLI tool to use AuthKeys, simply run the soracom configure command and follow the prompts to authenticate using AuthKeys.

You can configure multiple AuthKeys by using the --profile flag with Soracom CLI. Simply run soracom configure --profile <myOtherProfile> and follow the same prompts. Then when you use the soracom command with the --profile <myOtherProfile> flag, Soracom CLI will generate the API key and token using the AuthKeys that correspond to that profile.

When using the Soracom CLI, all authentication credentials are stored in plaintext in your ~/.soracom (Mac and Linux) or C:\Users\<user>\.soracom (Windows) directory. Take care to ensure that access to this data is secure.

The Soracom CLI tool will automatically request the API key and token so that you do not need to manually generate them before accessing other API endpoints. For example, to list the SIMs in your account, simply run:

soracom sims list

For more information, refer to the official Soracom CLI repository.

Account Security

AuthKeys

Overview

Access Control

Limitations

Compared to Credential Sets

Root Account AuthKeys

SAM User AuthKeys

API Authentication

Soracom API

Examples

Soracom CLI