API認証

APIキー

すべてのAPIリクエストは、アカウントに紐づくAPIキーで認証されます。キーはmk_live_に続く32文字の形式で、ダッシュボードのAPI keysで作成します。

当社では各キーのSHA-256ハッシュのみを保存するため、完全なキーが表示されるのは作成時の一度だけです。キーを紛失した場合は、新しいキーを作成して古いキーを無効化してください。プランによっては複数のキーを同時に保持できます。アプリケーションや環境ごとに1つのキーを使うのがおすすめです。

キーを送信する3つの方法

キーは、お使いのHTTPクライアントに合った方法で渡してください。次の3つの方法はいずれも同等です：

# 1. クエリパラメーター
curl "https://metalapi.com/api/v1/latest?api_key=YOUR_API_KEY"

# 2. Authorizationヘッダー（Bearerトークン）
curl "https://metalapi.com/api/v1/latest" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 3. X-API-Keyヘッダー
curl "https://metalapi.com/api/v1/latest" \
  -H "X-API-Key: YOUR_API_KEY"

本番環境ではヘッダーの使用をおすすめします。当社ではリクエストログを書き込む前にクエリ文字列からキーを削除しますが、お客様側のログ、プロキシ、エラートラッカーにはURL全体が残る可能性があります。

キーがない場合はエラー101、不明または無効化済みのキーの場合は102が返されます。いずれもHTTPステータスは401です。

ドメイン制限付きキー

クライアントサイドのJavaScriptからAPIを呼び出すと、キーがすべての訪問者に公開されます。どうしても必要な場合は、事前にダッシュボードでキーを自社ドメインに制限してください。

制限付きキーは、Origin（またはReferer）ヘッダーが許可されたドメインまたはそのサブドメインに一致するブラウザリクエストにのみ応答します。その他のウェブサイトからのリクエストはエラー107（HTTP 403）で拒否され、課金されません。

OriginやRefererヘッダーのないリクエスト（バックエンドからのサーバー間通信、cronジョブ、スクリプトなど）は常に許可されます。そのため、1つの制限付きキーでウェブサイトとサーバーの両方に対応できます。許可リストにexample.comを登録した場合の例：

# 許可：許可されたドメインのサブドメインからのブラウザリクエスト
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Origin: https://shop.example.com"

# 107で拒否：オリジンがリストにない
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Origin: https://another-site.com"

# 許可：OriginもRefererもないサーバー間リクエスト
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: YOUR_API_KEY"

キーを安全に保つ

• キーはサーバー上に置き、環境変数またはシークレットマネージャーから読み込んでください。Gitには絶対にコミットしないでください。
• アプリケーションと環境ごとに別々のキーを使えば、他に影響を与えずに1つだけ無効化できます。
• キーが漏えいした場合は、代わりのキーを作成してデプロイしたうえで、ダッシュボードで古いキーを無効化してください。
• APIは必ずhttps://経由で呼び出してください。
• 公開ウェブページでは、埋め込みウィジェットを使えば、ページにキーを含めずにリアルタイム価格を表示できます。

// サーバーサイドのみ：キーがブラウザに渡ることはありません
const res = await fetch("https://metalapi.com/api/v1/latest?currencies=XAU,XAG", {
  headers: { "X-API-Key": process.env.METALAPI_KEY },
});