APIの使用には認証情報が必要です。認証情報にはAPIキーとアクセストークンの2種類があり、利用する認証方式に応じて使い分ける必要があります。
利用可能な認証方式は以下になります。

表 1. 認証方式の種類
認証方式 内容 認証情報 有効期限

APIキー認証

キーに基づいてAPIの利用許可を与える認証方式。

APIキー

無期限

OAuth 2.0

OAuth 2.0(RFC 6749)に基づき、Client IDとClient Secretをもとに発行したアクセストークンにより、APIの利用許可を与える認証方式。

アクセストークン

発行から1時間

OAuth認証(従来方式)

従来より提供していたトークン形式の認証方式をI/F互換性維持のために提供。
Client ID、Client Secretおよび内部の動作はOAuth 2.0と共通化し、セキュリティを確保
従来I/Fの互換性維持を目的とした認証方式であり、OAuth 2.0の利用を推奨。

アクセストークン

発行から1時間

API使用手順

APIキー認証を使用する場合

  1. ポータルのAPIキー発行画面にて、APIキーを新規作成する。
    「グループ一覧」からグループを選択し「グループ詳細」を表示し、「グループ詳細」の「認証情報」タブの「APIキー認証情報」で [新規作成] をクリックします。

    APIキー
  2. APIキーを使って、各サービスのAPIを使用する。
    HTTPヘッダーに、以下のように指定します。
    'X-Api-Key:<APIキー>'

参考: PrimaryキーとSecondaryキーの活用

APIキーの利用期限は無期限ですが、セキュリティ上の理由(キーの不正利用など)でアプリケーションが使用するAPIキーの再発行が必要となることがあります。 ただ一つのAPIキーを使用する場合、アプリケーションはキーの再発行時に認証エラーとなり、処理が継続できなくなります。 このとき、アプリケーションで有効なキー(Secondaryのキーなど)を使用してリトライすることによりAPIの実行を継続することができます。

OAuth 2.0を使用する場合

  1. ポータルのOAuth認証情報発行画面にて、Client IDとClient Secretを新規作成する。
    「グループ一覧」からグループを選択し「グループ詳細」を表示し、「グループ詳細」の「認証情報」タブの「OAuth認証情報」で [新規作成] をクリックします。

    OAuth 2.0
  2. Client IDとClient Secretを使って、アクセストークンを取得する。
    API認証 API リファレンス を使用して取得します。
    アクセストークン取得手順は以下の通りです。

    1. 右上の錠アイコンをクリックします。

      POST_v2_tokens
    2. 手順 1 で作成したClient IDとClient SecretをそれぞれUsername欄およびPassword欄に入力後、[Authorize]をクリックします。

      POST_v2_tokens
    3. [Close]をクリックします。

      POST_v2_tokens
    4. /v2/tokens(POST) API で [Try it out] をクリックします。

      POST_v2_tokens
    5. [Execute]をクリックします。

      POST_v2_tokens
    6. Response body に "access_token" が通知されます。

      POST_v2_tokens
  3. アクセストークンを使って、各サービスのAPIを使用する。
    HTTPヘッダーに、以下のように指定します。
    'X-Access-Token:<アクセストークン>'

備考:アクセストークンの更新について

アクセストークンの有効期限が切れた場合は、同じ手順で再発行してください。

OAuth認証(従来方式)を使用する場合

  1. ポータルのOAuth認証情報発行画面にて、Client IDとClient Secretを新規作成する。
    「グループ一覧」からグループを選択し「グループ詳細」を表示し、「グループ詳細」の「認証情報」タブの「OAuth認証情報」で [新規作成] をクリックします。

    OAuth認証(従来方式)
  2. Client IDとClient Secretを使って、アクセストークンを取得する。
    API認証 API リファレンス を使用して取得します。
    アクセストークン取得手順は以下の通りです。

    1. /tokens(POST) API で [Try it out] をクリックします。

      POST_v1_tokens
    2. 赤枠の項目を入力し [Execute] をクリックします。
      Request body には、手順 1 で作成したClient IDとClient Secretを入力します。

      POST_v1_tokens
    3. Response body に "accessToken" が通知されます。

      POST_v1_tokens
  3. アクセストークンを使って、各サービスのAPIを使用する。
    HTTPヘッダーに、以下のように指定します。
    'X-Access-Token:<アクセストークン>'

備考:アクセストークンの更新について

当認証方式では、アクセストークン発行時にリフレッシュトークンが同時発行されます。
アクセストークンが有効期限切れになる前に、Client IDとClient Secretの代わりにリフレッシュトークンを使用して、API認証 API リファレンス の /tokens(PATCH) API でアクセストークンを再発行できます。
ただし、リフレッシュトークンの有効期限は発行から1日です。

備考: OAuth 2.0への移行方法

手順 2 でアクセストークン取得のために使用するAPI POST /v1/tokens を、「OAuth 2.0を使用する場合」の手順 2 で使用するAPI POST /v2/tokens に変更することで、OAuth 2.0へ移行できます。