APIキーの管理
APIキーは、ユーザーがケンオールAPIにアクセスするための資格情報です。
ケンオールAPIにアクセスするには、APIキーが必要です。
APIキーの種類
APIキーは2種類存在します。
- 公開キー: 住所入力フォームなど、公開されたページなどで使うことを前提としたAPIキー。設定したドメインからのみアクセス可能。
- シークレットキー: システム内部など、非公開の環境で使うことを前提としたAPIキー。
ダウンロードAPIなどの一部のAPIはシークレットキーの利用を前提としています。
APIリファレンスに特に記載がない場合は公開キーでそのAPIを利用できます。
シークレットキーは必要最低限の関係者のみがアクセスできるように厳重に管理し、決して第三者に共有しないようにしてください。
Originヘッダーの設定
Webの住所入力フォームなどでケンオールを利用する場合、APIキーをJavaScriptやHTML等に第三者に見える形で含めることになります。ケンオールではCORS (オリジン間リソース共有) の仕組みを使って、webブラウザからのアクセスをお客様のサイトからのみに限定することで、不正なAPIキーの利用を防いでいます。
ご利用に当たっては、お客様はあらかじめケンオールを利用したいwebサイトのドメイン名をAPIキーに指定する必要があります。
CORSについて詳しくは、以下のページを参照してください。
https://developer.mozilla.org/ja/docs/Web/HTTP/CORS
APIキー管理画面
ダッシュボードのAPIキーでは、APIキーの取得の他、作成や削除といった管理操作を行うことができます。
APIキーを取得する
ログイン直後は、1つの公開キーのみが生成されています。
公開キーのAPIキーフィールドには、APIキーの一部のみ表示されています。
この文字列をクリックすると、完全なAPIキーをクリップボードにコピーすることができます。
APIキーを新規作成する
2022/08/31まで販売していた郵便番号APIプランでは、公開キーとシークレットキーを1つずつまでしか作成することができません。
複数のAPIキーを利用したい場合は新しいスタンダードプランをご利用ください。
プランと利用料金のページもご参照ください。
右上のAPIキー作成ボタンを押すと、APIキーを新規作成することができます。
APIキー作成時に、以下の情報を入力します。
名前: APIキーにつける名前です。最大256文字まで入力できます。空欄にした場合、
名前未設定と表示されます。種類: APIキーの種類です。詳細はAPIキーの種類を参照してください。この設定は必須です。作成後は変更することができません。
Originヘッダー設定:
APIリクエストを発行するWebページのドメイン名を一つまたは複数指定します。
複数のドメイン名を許可する場合はカンマ (
,) 区切りで入力してください。ドメイン名のみを入力してください。例えば、
example.comを設定したい場合、https://example.comというURLでの表記は使用しないでください。オプションの有無によって、ドメイン名のマッチングルールが異なります。
オプションなし (通常のプラン): ドメイン名は、完全一致である必要があります。
許可ドメインワイルドカードオプションをご購入の場合:
.で区切られたドメイン名の構成要素 (サブドメイン名) にワイルドカード (*) 文字を利用できます。ワイルドカードを含むドメイン名は、ワイルドカードを含まないドメイン名と同様にカンマ (,) 区切りで列挙できます。以下にワイルドカードを含むドメイン名の例を示します。
*.foo.example.com
bar.*.example.comなお、
*.foo.example.comと記述した場合、*は、それが位置するサブドメインのみを対象としたワイルドカードとなり、配下のサブドメインを暗黙に許可しません。つまり、この場合bar.foo.example.comは許可されますが、baz.bar.foo.example.comは許可対象となりません。もしbaz.bar.foo.example.comも許可対象としたい場合には、*.*.foo.example.comをドメイン名の一覧に含める必要があります。cautionワイルドカード文字はサブドメイン名の一部にマッチすることができません。次のような指定は無効となります。
foo*.example.com
*bar.example.com
有効期限: APIキーの有効期限です。この期間をすぎるとこのAPIキーを使うことができなくなります。デフォルトは無期限です。1
コメント: APIキーの補足説明などの自由記述欄です。最大4096文字まで入力できます。
情報を入力したら、作成するボタンを押します。
APIキーが作成されます。
APIキーを編集する
APIキーの右にある、縦に点が3つ並んだ記号を押すと、各APIキーの管理メニューが表示されます。
APIキーの編集 をクリックすると、APIキーの情報を編集することができます。
編集できる項目は以下のとおりです。
- 名前: APIキーにつける名前です。最大256文字まで入力できます。空欄にした場合、空欄のままとなります。
- Originヘッダー設定: APIリクエストを発行するWebページのドメインを指定します。複数のドメインを許可する場合はカンマ区切りで入力してください。ドメイン名は、完全一致である必要があります。Originヘッダーの設定も参照してくだい。
- 有効期限: APIキーの有効期限です。この期間をすぎるとこのAPIキーを使うことができなくなります。デフォルトは無期限です。1
- デフォルトのAPIバージョン: APIバージョニングで、バージョンが指定されなかった場合のデフォルト値を指定します。
- コメント: APIキーの補足説明などの自由記述欄です。最大4096文字まで入力できます。
Originヘッダー設定時には以下の点に注意してください。
- ドメイン名のみを入力してください。例えば、
example.comを設定したい場合、https://example.comという表記は利用しないでください。 - ドメイン名には、ワイルドカードを使用することはできません。例えば、
*や*.example.comという表記は利用できません。
APIキーの更新状態が反映されるまで10分ほどかかることがあります。
APIキーの種類は変更することはできません。
情報を編集したら、保存するボタンを押します。
APIキーの情報が更新されます。
APIキーを複製する
APIキー管理メニューからAPIキーを複製をクリックすると、APIキーを複製することができます。
APIキーを削除する
APIキー管理メニューからAPIキーを削除をクリックすると、APIキーを削除することができます。
表示される内容を確認し、問題がなければ削除するを押します。
APIキーが削除されます。
APIキーの削除は取り消すことができません。
削除状態が反映されるまで10分ほどかかることがあります。
APIキーを編集して有効期限を過去の日時に設定することで、APIキーを削除せずに無効化することができます。
APIキーのコメントを表示する
APIキーにコメントを設定している場合、APIキーの名前にカーソルを合わせるとコメントを表示できます。
- 正確にはデフォルトの有効期限は2999年12月31日に設定されています。ケンオールでは1000年続くようなサービスに利用されることを想定しておりませんので、1000年以上動作するサービスにご利用の際はご注意ください。↩