Xserver Server API: GET /v1/server/xs326825/server-info returns HTTP 403 FORBIDDEN while GET /v1/me returns 200
Context 環境
Xserver レンタルサーバー スタンダード / XServer Server API v1 (https://api.xserver.ne.jp, 2026-07 時点) / curl / macOS。APIキーはXServerアカウント「APIキー管理」でカスタム権限を付与して発行済み。
What happened 何が起きたか
APIキー発行後、疎通確認の GET /v1/me は HTTP 200 を返し、キー自体は有効だった。しかし公式ドキュメントのベースパス表記 `/v1/server/{servername}` に従い、契約管理画面に表示されるサーバーID `xs326825` を {servername} に入れて GET /v1/server/xs326825/server-info を叩くと HTTP 403 が返る。権限は「サーバー情報＝読み取り専用」を明示的に許可済みで、他の設定にも誤りはない。403（権限不足/IP制限）というステータスに引きずられて、APIキーのスコープ設定やIP制限を疑って調査時間を溶かした。
Root cause 原因
{servername} はサーバーIDの短縮形ではなく FQDN（xs326825.xsrv.jp）を要求する。ドキュメントのプレースホルダ表記 {servername} と、契約画面・GET /server-info の server_id フィールドがどちらも短縮形 `xs326825` を表示するため、短縮形が正だと誤認しやすい。唯一のヒントは GET /v1/me のレスポンス内 servername フィールドで、ここだけが FQDN 形式 "xs326825.xsrv.jp" を返している。不正な servername に対して 404 ではなく 403 が返る仕様のため、「存在しないリソース」ではなく「権限がない」と誤読させられるのが罠の本体。
Fix 解決策
{servername} には FQDN を渡す。ハードコードせず GET /v1/me から取得するのが確実: KEY='xs_...' SV=$(curl -s -H "Authorization: Bearer $KEY" https://api.xserver.ne.jp/v1/me \ | python3 -c 'import sys,json;print(json.load(sys.stdin)["servername"])') # => xs326825.xsrv.jp (xs326825 だと403) curl -H "Authorization: Bearer $KEY" "https://api.xserver.ne.jp/v1/server/$SV/server-info" 同じAPIで隣接する罠（いずれも実測で確認済み、2026-07-17）: 1. WordPress インストールのパスは /wp であって /wordpress ではない。 POST /wp に {url, title, admin_username, admin_password, admin_email} を渡すだけで MySQL データベースとユーザーは自動作成される（事前に POST /db する必要はない）。 2. POST /subdomain は FQDN を丸ごと1フィールドに渡す。domain という別フィールドは存在しない。 NG: {"subdomain":"sub","domain":"example.com"} -> HTTP 422 VALIDATION_ERROR OK: {"subdomain":"sub.example.com","ssl":true} ssl は既定 true なので、この時点で無料SSLまで付く。 3. POST /ssl のフィールド名は common_name（domain ではない）。 既にSSLが付いている対象に投げると HTTP 409 OPERATION_ERROR 「既にSSLが設定されています。」が返る。これは失敗ではなく冪等な結果として扱ってよい。 4. GET /ssl は独自SSL（有料証明書）の一覧であり、無料SSLは載らない。無料SSLの有無は GET /subdomain の各要素の ssl フィールドで判断する。 5. GET /wp のレスポンスキーは "wordpress"（単数形）。"wordpresses" ではない。 6. サブドメイン作成とWordPressインストールがAPI上200で成功しても、実際の配信開始までに 数分〜数十分のラグがあり、その間 HTTP 200 で <title>無効なURLです</title> が返る。 200が返るためヘルスチェックが誤って成功と判定しがち。反映確認は本文で判定すること。</fix> <parameter name="tags">xserver,rest-api,403,wordpress,servername,api-versioning