Salesforce External Credentialで「invalid x-api-key」エラーの真因と解決策

どんな取り組みか
使われた技術スタック
実装のポイント
得られた成果や学び
まとめ

どんな取り組みか

Salesforce（Apex）から外部API（Claude API）を呼び出す際に発生した「invalid x-api-key」エラーについて、その原因と解決策を解説する技術ブログ記事です。APIキーをコードに直接書き込まず、Named CredentialとExternal Credentialに格納し、カスタムHTTPヘッダー `x-api-key` に流し込む構成で問題が発生しました。

使われた技術スタック

Salesforce (Apex)
External Credential
Named Credential
Claude API

実装のポイント

外部API呼び出しにおいて、APIキーをSalesforceのExternal Credentialに格納し、カスタムHTTPヘッダー `x-api-key` に設定する際、「invalid x-api-key」というHTTP 401エラーが継続して発生しました。このエラーは、リクエストが外部APIまで届いているものの、ヘッダーの値が空または不正であることを示唆していました。

原因究明の過程で、以下の点が明らかになりました。

APIキーの有効性確認: Salesforceから切り離し、curlコマンドを用いてAPIキー単体の有効性を検証した結果、キー自体は有効であることが確認されました。これにより、問題はSalesforce側の設定にあると特定されました。
秘密パラメーターの取り扱い: External Credentialの認証パラメーター（APIキーなど秘密情報を含むもの）は、セキュリティ上の理由からTooling APIやMetadata APIの取得結果には含まれません。そのため、メタデータ上で見えないことが「保存されていない」ことを意味するわけではないという点に注意が必要です。
カスタムプロトコルの制約: カスタム認証プロトコルでは、秘密パラメーターをメタデータで配布できないことが確認されました。格納はUIまたはConnect API経由でのみ可能です。
真因: Named Credentialの設定において、<allowMergeFieldsInHeader> が false に設定されていたことが根本原因でした。この設定が false の場合、カスタムヘッダーに記述された {!$Credential.Anthropic.ApiKey} のようなマージフィールド（式）が評価されず、リテラル文字列として（あるいは空として）送信されてしまいます。

この問題を解決するためには、Named Credentialの設定で <allowMergeFieldsInHeader> を true に変更する必要があります。これにより、マージフィールドが正しく評価され、APIキーがヘッダーに含められるようになります。

また、SalesforceのUIにおける「Named Credentials」の日本語訳は「指定ログイン情報」、「External Credentials」タブは「外部ログイン情報」であることが、検索時に混乱を招く可能性があるという副次的な情報も共有されています。認証パラメーターの名前を間違えた場合（例: `Apikey` を `ApiKey`）、リネームはサポートされておらず、一度削除して再作成する必要がある点も注意が必要です。

得られた成果や学び

本件を通じて、以下の教訓が得られました。

「見えない」ことが必ずしも「無い」ことを意味しない。特に秘密情報を含む認証パラメーターは、メタデータ取得時には表示されない。
問題の切り分けは、疑っている要素を一つずつ外部から独立して検証することが重要である。今回は、APIキー単体の有効性をcurlで確認し、Salesforce側の設定問題に絞り込んだ。
設定フラグ（例: allowMergeFieldsInHeader）が原因である場合、根本的な原因を見誤ると、保存されていないと思い込んで無駄な手順を踏む可能性がある。
SalesforceのUIにおける用語（「指定ログイン情報」など）の正確な理解も、トラブルシューティングを円滑に進める上で役立つ。

最終的に、allowMergeFieldsInHeader を true に設定することで、APIキーが正しくヘッダーに設定され、外部API呼び出しは一発で成功しました。

まとめ

SalesforceのExternal Credentialを使用して外部APIを呼び出す際、「invalid x-api-key」エラーに遭遇した場合、Named Credentialの allowMergeFieldsInHeader 設定が true になっているかを確認することが重要です。また、秘密パラメーターの取り扱いや、問題切り分けの重要性についても理解を深めることができました。

出典: https://qiita.com/hibiki-ishida/items/167c16b7b764f55bc247

Related Certifications