APIの使用には認証情報が必要です。認証情報にはAPIキーとアクセストークンの2種類があり、利用する認証方式に応じて使い分ける必要があります。
利用可能な認証方式は以下になります。
認証方式 | 内容 | 認証情報 | 有効期限 |
---|---|---|---|
APIキー認証 |
キーに基づいてAPIの利用許可を与える認証方式。 |
APIキー |
無期限 |
OAuth 2.0 |
OAuth 2.0(RFC 6749)に基づき、Client IDとClient Secretをもとに発行したアクセストークンにより、APIの利用許可を与える認証方式。 |
アクセストークン |
発行から1時間 |
OAuth認証(従来方式) |
従来より提供していたトークン形式の認証方式をI/F互換性維持のために提供。 |
アクセストークン |
発行から1時間 |
API使用手順
APIキー認証を使用する場合
-
ポータルのAPIキー発行画面にて、APIキーを新規作成する。
「グループ一覧」からグループを選択し「グループ詳細」を表示し、「グループ詳細」の「認証情報」タブの「APIキー認証情報」で [新規作成] をクリックします。 -
APIキーを使って、各サービスのAPIを使用する。
HTTPヘッダーに、以下のように指定します。
'X-Api-Key:<APIキー>'
参考: PrimaryキーとSecondaryキーの活用
APIキーの利用期限は無期限ですが、セキュリティ上の理由(キーの不正利用など)でアプリケーションが使用するAPIキーの再発行が必要となることがあります。 ただ一つのAPIキーを使用する場合、アプリケーションはキーの再発行時に認証エラーとなり、処理が継続できなくなります。 このとき、アプリケーションで有効なキー(Secondaryのキーなど)を使用してリトライすることによりAPIの実行を継続することができます。 |
OAuth 2.0を使用する場合
-
ポータルのOAuth認証情報発行画面にて、Client IDとClient Secretを新規作成する。
「グループ一覧」からグループを選択し「グループ詳細」を表示し、「グループ詳細」の「認証情報」タブの「OAuth認証情報」で [新規作成] をクリックします。 -
Client IDとClient Secretを使って、アクセストークンを取得する。
API認証 API リファレンス を使用して取得します。
アクセストークン取得手順は以下の通りです。-
右上の錠アイコンをクリックします。
-
手順 1 で作成したClient IDとClient SecretをそれぞれUsername欄およびPassword欄に入力後、[Authorize]をクリックします。
-
[Close]をクリックします。
-
/v2/tokens(POST) API で [Try it out] をクリックします。
-
[Execute]をクリックします。
-
Response body に "access_token" が通知されます。
-
-
アクセストークンを使って、各サービスのAPIを使用する。
HTTPヘッダーに、以下のように指定します。
'X-Access-Token:<アクセストークン>'
備考:アクセストークンの更新について
アクセストークンの有効期限が切れた場合は、同じ手順で再発行してください。 |
OAuth認証(従来方式)を使用する場合
-
ポータルのOAuth認証情報発行画面にて、Client IDとClient Secretを新規作成する。
「グループ一覧」からグループを選択し「グループ詳細」を表示し、「グループ詳細」の「認証情報」タブの「OAuth認証情報」で [新規作成] をクリックします。 -
Client IDとClient Secretを使って、アクセストークンを取得する。
API認証 API リファレンス を使用して取得します。
アクセストークン取得手順は以下の通りです。-
/tokens(POST) API で [Try it out] をクリックします。
-
赤枠の項目を入力し [Execute] をクリックします。
Request body には、手順 1 で作成したClient IDとClient Secretを入力します。 -
Response body に "accessToken" が通知されます。
-
-
アクセストークンを使って、各サービスのAPIを使用する。
HTTPヘッダーに、以下のように指定します。
'X-Access-Token:<アクセストークン>'
備考:アクセストークンの更新について
当認証方式では、アクセストークン発行時にリフレッシュトークンが同時発行されます。 |
備考: OAuth 2.0への移行方法
手順 2 でアクセストークン取得のために使用するAPI |