Soracom

Users

開発者向けツール

API キーと API トークンの取り扱いについて

SORACOM API (以下、API) を呼び出す際は、API キーと API トークンが必要です。これらの情報は、他人に知られないよう秘密にしてください。

API を複数回呼び出す場合の手順は、以下のとおりです。

  1. Auth:auth API を呼び出して、SAM ユーザーまたはルートユーザーの API キーと API トークンを発行します。

    SAM ユーザーの API キーと API トークンを発行するために必要な情報と、ルートユーザーの API キーと API トークンを発行するために必要な情報は異なります。詳しくは、API キーと API トークンを発行する を参照してください。

  2. 手順 1 で発行した API キーと API トークンを指定して API を複数回呼び出します。

    API キーと API トークンが漏洩した可能性がある場合
    Auth:auth API を呼び出してから、Auth:logout API を呼び出すまでに、API キーと API トークンが漏洩した可能性がある場合は、無効化してください。詳しくは、API キーと API トークンを無効化する を参照してください。

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

  3. API の呼び出しがすべて終わったら、Auth:logout API を呼び出して API キーと API トークンを無効化します。

API トークンを検証して別の用途で利用することはできません

API トークンは JSON ウェブトークン (JWT) です。JWT には内容が改ざんされていないことを検証するための仕組みがあり、SORACOM プラットフォームでもその仕組みを利用しています。

ただし、検証するための情報は、一般には公開していません。したがって、SORACOM プラットフォーム以外の環境では、API トークンが改ざんされていないことを検証できません。SORACOM プラットフォーム以外から取得した API トークンの内容は利用しないでください。

発行済みの API トークンの有効期間だけを延長することはできません

有効期間が経過する前に Operator:generateAuthToken API を呼び出すと、新しい API トークンを発行できます。

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

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

API キーと API トークンの有効期間について

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

API キーと API トークンを発行する

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

なお、ルートユーザーと SAM ユーザーの違いについては、ルートユーザーと SAM ユーザーの違い を参照してください。

発行した API キーと API トークンの取り扱いに注意してください
  • API キーと API トークンが漏洩すると、SAM ユーザーまたはルートユーザーの権限で API が実行されてしまいます。ルートユーザーはすべての API を実行できるため、利用できる API を制限 (権限を設定) できる SAM ユーザーの API キーと API トークンを使用することを推奨します。
  • API キーと API トークンが不要になった場合や、漏洩した可能性がある場合は、無効化してください。詳しくは、API キーと API トークンを無効化する を参照してください。

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

SAM ユーザーの API キーと API トークンを発行する

SAM ユーザーとして API を呼び出す場合は、SAM ユーザーに API を呼び出すための権限を設定し、以下のいずれかの方法で Auth:auth API を呼び出して API キーと API トークンを発行します。権限設定について詳しくは、SAM ユーザーを作成する を参照してください。

SAM ユーザーに権限を設定してから API キーと API トークンを発行してください

SAM ユーザーの権限設定を変更したときは、その変更を適用するために API キーと API トークンを再発行してください。たとえば、Query:searchSims API を呼び出すには、SAM ユーザーに Query:searchSims API を呼び出すための権限を設定してから、API キーと API トークンを発行します。権限設定について詳しくは、SAM ユーザーの権限設定 を参照してください。

  • 認証キー ID、および認証キーシークレットを使用して認証する。

    $ curl -X POST https://api.soracom.io/v1/auth \
    -H "Content-Type: application/json" \
    -d '{
      "authKeyId": "keyId-xxxxxxx",
      "authKey": "secret-xxxxxxx"
    }'
    
    # Response:
    # 200 OK
    #
    # {
    #   "apiKey": "API キー",
    #   "operatorId": "オペレーター ID",
    #   "userName": "SAM ユーザー名",
    #   "token": "API トークン"
    # }
    
  • オペレーター ID、SAM ユーザー名、およびコンソールログインパスワードを使用して認証する。

    curl -X POST https://api.soracom.io/v1/auth \
    -H "Content-Type: application/json" \
    -d '{
      "operatorId": "オペレーター ID",
      "userName": "SAM ユーザー名",
      "password": "コンソールログインパスワード"
    }'
    
    # Response:
    # 200 OK
    #
    # {
    #   "apiKey": "API キー",
    #   "operatorId": "オペレーター ID",
    #   "userName": "SAM ユーザー名",
    #   "token": "API トークン"
    # }
    

多要素認証を有効にしている場合は、mfaOTPCode に OTP を指定します。

ルートユーザーの API キーと API トークンを発行する

ルートユーザーとして API を呼び出す場合は、Auth:auth API を呼び出して API キーと API トークンを発行します。

  • 認証キー ID、および認証キーシークレットを使用して認証する。

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

    $ curl -X POST https://api.soracom.io/v1/auth \
    -H "Content-Type: application/json" \
    -d '{
      "email": "email@example.com",
      "password": "superStrongPassw0rd"
    }'
      
    # Response:
    # 200 OK
    #
    # {
    #   "apiKey": "API キー",
    #   "operatorId": "オペレーター ID",
    #   "token": "API トークン"
    # }
    

多要素認証を有効化している場合は、mfaOTPCode に OTP を指定します。

API キーと API トークンを無効化する

API の呼び出しが終わったら、Auth:logout API を呼び出して API キーと API トークンを無効化してください。

$ curl -X POST http://api.soracom.io/v1/auth/logout \
-H "X-Soracom-API-Key: $X_SORACOM_API_KEY" \
-H "X-Soracom-Token: $X_SORACOM_TOKEN"
API キーと API トークンが漏洩した可能性がある場合

API キーと API トークンが漏洩した可能性がある場合は、以下のいずれかの API を呼び出して、API キーと API トークンを無効化してください。

  • SAM ユーザーの API キーと API トークンを無効化する: User:revokeUserAuthTokens API

    $ curl -X DELETE http://api.soracom.io/v1/operators/${operator_id}/users/${user_name}/tokens \
    -H "X-Soracom-API-Key: $X_SORACOM_API_KEY" \
    -H "X-Soracom-Token: $X_SORACOM_TOKEN"
    
  • ルートユーザーの API キーと API トークンを無効化する: Operator:revokeOperatorAuthTokens API

    $ curl -X DELETE http://api.soracom.io/v1/operators/${operator_id}/tokens \
    -H "X-Soracom-API-Key: $X_SORACOM_API_KEY" \
    -H "X-Soracom-Token: $X_SORACOM_TOKEN"
    

SAM ユーザーを削除したり、オペレーターを削除したりしても、API キーと API トークンが無効化されます。

API キーと API トークンを無効化すると

無効化された API キーと API トークンを利用して、API を呼び出すことはできません。

  • SORACOM API を呼び出した場合: Invalid API key エラーが返されます。
  • SORACOM CLI を実行した場合:
    • soracom sims list などのコマンドを実行するたびに API キーと API トークンを取得する仕組みです。つまり、1 回発行された API キーと API トークンは再利用されないため、API キーと API トークンを無効化しても、無効化する前と変わらずに SORACOM CLI を実行できます。
    • API キーと API トークンの発行頻度を減らす の説明のように API キーと API トークンを再利用しているときは、Invalid API key エラーが返されます。
  • ユーザーコンソールにログインしている場合: API キーと API トークンが無効化されたユーザーが操作すると、ログイン画面に戻されます。