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:

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:

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

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:

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

    https://console.soracom.io

    Security

  2. From the Security screen, click the AuthKeys tab. Then click the Create an AuthKey button.

    https://console.soracom.io

    AuthKeys

  3. An AuthKey ID and AuthKey Secret key pair will be automatically generated.

    Create AuthKey

    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:

To generate or revoke an AuthKey for a SAM User:

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

    https://console.soracom.io

    Security

  2. From the Security screen, click the Users tab. Then click the name of the SAM User you want to manage.

    https://console.soracom.io

    Select SAM User

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

    Edit User Authentication

  4. An AuthKey ID and AuthKey Secret key pair will be automatically generated.

    Create AuthKey

    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 the SAM User.

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:

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

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

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.