第1章 API キーの API

ユーザーアカウントおよびアプリの各種 API キーを管理します。

注記

X-FH-AUTH-USER はすべてのリクエストのすべてのヘッダーになければなりません。詳細は、API キーの管理 を参照してください。

1.1. API キーの一覧表示

1.1.1. 説明

ユーザーまたはアプリ API キーを一覧表示します。

1.1.2. エンドポイント

  • URI: /box/srv/1.1/ide/<domain>/api/list
  • メソッド: POST

1.1.3. リクエストボディー

1.1.3.1. 現在ログインしているユーザーのキーを一覧表示

{
  "type": "user"
}

1.1.3.2. 指定されたアプリ ID に属するキーの一覧表示

{
  "type": "app",
  "appId": "<app_instance_id>"
}

1.1.4. レスポンスボディー

1.1.4.1. 成功

{
  "status": "ok",
  "list": [{
    "label": "<user_friendly_id>",
    "keyType": "<key_type>",
    "key": "<public_api_key>",
    "keyReference": "<reference_id>", // for example, user/app id
    "secret": "<api_secret_key>",  // only for 'admin' group
    "revoked": "<revoked_timestamp>",
    "revokedBy": "<revoked_by_ref_id>", // for example, user id
    "revokedEmail": "<revoked_by_user_email>"
  },
  /* ... */
  ]
}

1.1.4.2. エラー

{
  "status": "error",
  "message": "<error_message>"
}

1.2. 新規 API キーの作成

1.2.1. 説明

新規ユーザーまたはアプリ API キーを作成します。ユーザーは関連付けられた複数の API キーを持つことができますが、アプリには、常に 1 つのアクティブな API キーしか持たせることができません。アプリ API キーが作成されると、アプリの既存のキーは自動的に失効します。

1.2.2. エンドポイント

  • URI: /box/srv/1.1/ide/<domain>/api/create
  • メソッド: POST

1.2.3. リクエストボディー

1.2.3.1. 現在ログインしているユーザーの API キーを作成

{
  "type": "user",
  "label": "<user_friendly_id>"
}

1.2.3.2. 指定されたアプリ ID に属する新規 API キーを作成

このアプリのすべての既存キーは自動的に失効します。 

{
  "type": "app",
  "label": "<user_friendly_id>",
  "appId": "<app_instance_id>"
}

1.2.4. 成功

{
  "status": "ok",
  "apiKey": {
    "label": "<user_friendly_id>",
    "keyType": "<key_type>",
    "key": "<public_api_key>",
    "keyReference": "<reference_id>", // for example, user/app id
    "secret": "<api_secret_key>",  // only for 'admin' group
    "revoked": "<revoked_timestamp>",
    "revokedBy": "<revoked_by_ref_id>", // for example, user id
    "revokedEmail": "<revoked_by_user_email>"
  }
}

1.2.5. エラー

{
  "status": "error",
  "message": "<error_message>"
}

1.3. 既存 API キーの失効

1.3.1. 説明

既存ユーザーまたはアプリ API キーを失効させます。

1.3.2. エンドポイント

  • URI: /box/srv/1.1/ide/<domain>/api/revoke
  • メソッド: POST

1.3.3. リクエストボディー

{
  "key": "<public_api_key>"
}

1.3.4. 成功

{
  "status": "ok",
  "apiKey": {
    "label": "<user_friendly_id>",
    "keyType": "<key_type>",
    "key": "<public_api_key>",
    "keyReference": "<reference_id>", // for example, user/app id
    "secret": "<api_secret_key>",  // only for 'admin' group
    "revoked": "<revoked_timestamp>",
    "revokedBy": "<revoked_by_ref_id>", // for example, user id
    "revokedEmail": "<revoked_by_user_email>"
  }
}

1.3.5. エラー

{
  "status": "error",
  "message": "<error_message>"
}

1.4. 既存 API キーの削除

1.4.1. 説明

既存ユーザーまたはアプリ API キーを完全に削除します。

1.4.2. エンドポイント

  • URI: /box/srv/1.1/ide/<domain>/api/delete
  • メソッド: POST

1.4.3. リクエストボディー

{
  "key": "<public_api_key>"
}

1.4.4. 成功

{
  "status": "ok",
  "apiKey": {
    "label": "<user_friendly_id>",
    "keyType": "<key_type>",
    "key": "<public_api_key>",
    "keyReference": "<reference_id>", // for example, user/app id
    "secret": "<api_secret_key>",  // only for 'admin' group
    "revoked": "<revoked_timestamp>",
    "revokedBy": "<revoked_by_ref_id>", // for example, user id
    "revokedEmail": "<revoked_by_user_email>"
  }
}

1.4.5. エラー

{
  "status": "error",
  "message": "<error_message>"
}

1.5. 既存 API キーの更新

1.5.1. 説明

既存 App またはユーザー API キーを更新します。

1.5.2. エンドポイント

  • URI: /box/srv/1.1/ide/<domain>/api/update
  • メソッド: POST

1.5.3. リクエストボディー

{
  "key": "<public_api_key>",
  "fields": {
    "label": "<new_user_friendly_id>"
  }
}

1.5.4. 成功

{
  "status": "ok",
  "apiKey": {
    "label": "<user_friendly_id>",
    "keyType": "<key_type>",
    "key": "<public_api_key>",
    "keyReference": "<reference_id>", // for example, user/app id
    "secret": "<api_secret_key>",  // only for 'admin' group
    "revoked": "<revoked_timestamp>",
    "revokedBy": "<revoked_by_ref_id>", // for example, user id
    "revokedEmail": "<revoked_by_user_email>"
  }
}

1.5.5. エラー

{
  "status": "error",
  "message": "<error_message>"
}

1.6. API キーの検証

1.6.1. 説明

API キーが有効であるかどうかを検査します。

1.6.2. エンドポイント

  • URI: /box/srv/1.1/ide/<domain>/api/validate
  • メソッド: POST

1.6.3. リクエストボディー

{
  "type" : "<key_type>"
  "key" : "<key_value>",
}

1.6.4. 成功

{
  "status" : "ok",
  "valid" : true | false
}

1.6.5. エラー

{
  "status" : "error",
  "message" : "<error_message>"
}