API キーと API トークンの取り扱いについて
SORACOM API (以下、API) を呼び出す際は、API キーと API トークンが必要です。これらの情報は、他人に知られないよう秘密にしてください。
API トークンを検証して別の用途で利用することはできません
API トークンは JSON ウェブトークン (JWT) です。JWT には内容が改ざんされていないことを検証するための仕組みがあり、SORACOM プラットフォームでもその仕組みを利用しています。
ただし、検証するための情報は、一般には公開していません。したがって、SORACOM プラットフォーム以外の環境では、API トークンが改ざんされていないことを検証できません。SORACOM プラットフォーム以外から取得した API トークンの内容は利用しないでください。
発行済みの API トークンの有効期間だけを延長することはできません
有効期間が経過する前に Operator:generateAuthToken API
を呼び出すと、新しい API トークンを発行できます。
一部の API では API キーと API トークンは必要ありません
例外的に以下の API では、API キーと API トークンは必要ありません。
- Auth
- Device
https://api.soracom.io/v1/devices/{device_id}/publish
(ステップ 3: Harvest Data にデータを送信する を参照してください)
- Operator
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、および認証キーシークレットを使用して認証する。
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 https://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 https://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 https://api.soracom.io/v1/operators/${operator_id}/tokens \ -H "X-Soracom-API-Key: $X_SORACOM_API_KEY" \ -H "X-Soracom-Token: $X_SORACOM_TOKEN"
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 トークンが無効化されたユーザーが操作すると、ログイン画面に戻されます。