Soracom

Users

開発者向けツール

API キーと API トークン

SORACOM API を呼び出す際は、API キーと API トークンが必要です。

一部の API では API キーと API トークンは必要ありません

例外的に以下の API では、API キーと API トークンは必要ありません。

API キー 

API キーは、API を呼び出した SORACOM アカウント (オペレーター) を識別するためのユニークな文字列です。API キーを利用して、アクセス権限が確認されます。他人に知られないよう秘密にしておく必要があります。

API トークン 

API トークンは API による操作のセッション (以下、API セッション) を識別するためのユニークなキーです。つまり、同一の API トークンを利用した API 呼び出しを複数まとめたものが 1 つの API セッションです。新たな API セッションを開始するには、API トークンを再発行します。

API トークンの有効期間 

API トークンには、有効期間があります。デフォルトは 24 時間 (86400 秒) です。API トークンの有効期間は、API トークンを発行するときに 3 分 (180 秒) ~ 48 時間 (172800 秒) の範囲で指定できます。

なお、発行済みの API トークンの有効期間を延長することはできません。ただし、有効期間が経過する前に Operator:generateAuthToken を呼び出すと、新しい API トークンを発行できます。

適切な有効期間を指定してください

有効期間を短く設定すると、API トークンが漏洩した場合の被害を抑えることが期待できます。一方で、短すぎると発行回数が増えて利便性が落ちます。システムの要件に応じて有効期間を指定してください。

たとえば、CLI スクリプトのように、一度実行したら API を一つだけ呼び出して数秒で終了する場合は、有効期間は数分程度で十分です。また、GUI アプリケーションのように、人間がインタラクティブに操作する場合は、有効期間を 30 分~1 時間程度にするのがちょうど良いかもしれません。

API キーと API トークンの発行方法 

Auth:auth を呼び出して、認証を行い API キーと API トークンを発行します。ルートユーザーとして API を呼び出す場合と SAM ユーザー として API を呼び出す場合で、指定する情報が異なります。

API キーと API トークンは安全な場所に保存してください

API キーと API トークンが漏洩すると、ルートユーザーまたは SAM ユーザーの権限で API が実行されてしまいます。安全な場所に保存してください。

なお、API キーと API トークンはいつでも発行できます。発行した API キーと API トークンを永続的に保存しておく必要はありません。

ルートユーザー 

ルートユーザーとして API を呼び出す場合は、以下のいずれかの方法で認証します。

  • 認証キー ID、および認証キーシークレットを使用して認証する。
  • メールアドレス、およびパスワードを使用して認証する。

メールアドレス、およびパスワードを使用して認証する例:

$ curl  -X POST \
      -H "Content-Type: application/json" \
      -d '{
              "email": "email@example.com",
              "password": "superStrongPassw0rd"
          }' \
      https://api.soracom.io/v1/auth

# Response:
# 200 OK
#
# {
#   "apiKey": "API キー",
#   "operatorId": "オペレーター ID",
#   "token": "API トークン"
# }
多要素認証を有効にしている場合は、mfaOTPCode に OTP を指定します。

SAM ユーザー 

SAM ユーザーとして API を呼び出す場合は、以下のいずれかの方法で認証します。必要な情報については、SAM ユーザーを作成する を参照してください。

  • 認証キー ID、および認証キーシークレットを使用して認証する。
  • オペレーター ID、SAM ユーザー名、およびコンソールログインパスワードを使用して認証する。

認証キー ID、および認証キーシークレットを使用する例:

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

# Response:
# 200 OK
#
# {
#   "apiKey": "API キー",
#   "operatorId": "オペレーター ID",
#   "userName": "SAM ユーザー名",
#   "token": "API トークン"
# }
多要素認証を有効にしている場合は、mfaOTPCode に OTP を指定します。