API 使用手冊API manual

jt-ipam 的 REST API、phpIPAM 相容層、Graylog 查表與 MCP。以下所有網址請把 https://ipam.example.com 換成你自己的位址。 The jt-ipam REST API, phpIPAM compatibility layer, Graylog lookups and MCP. Replace https://ipam.example.com below with your own address.

1認證：API 權杖Auth: API tokens

外部程式一律用 API 權杖，不要用帳號密碼登入拿 JWT（JWT 只有 15 分鐘、是給網頁前端用的）。 External programs should always use an API token rather than logging in for a JWT (JWTs last 15 minutes and exist for the web UI).

怎麼取得權杖Getting a token

登入 jt-ipam → 右上角使用者選單 → API 權杖 → 新增。填名稱、有效天數（1～365，預設 90）、權限範圍，按儲存。 Sign in to jt-ipam → user menu (top right) → API tokens → Add. Give it a name, a lifetime (1–365 days, default 90) and a scope, then save.

怎麼帶權杖Sending the token

curl -H "Authorization: Bearer jt_prod_xxxxxxxxxxxxxxxx" \
  https://ipam.example.com/api/v1/subnets

權杖首碼 jt_ 會讓後端自動辨識為 API 權杖（沒有這個首碼則當成 JWT 解析）。 The jt_ prefix tells the backend this is an API token (without it, the value is parsed as a JWT).

權限範圍（scope）Scopes

目前只支援這兩種。填其他值（例如 write、subnets:read）建立時就會被拒絕回 422 —— 這是刻意的：不提供無法真正強制執行的權限旋鈕。 These are the only two supported. Any other value (e.g. write, subnets:read) is rejected with 422 at creation — deliberately, so there is no knob that looks like a restriction but isn't enforced.

用 API 管理權杖Managing tokens via the API

curl -X POST https://ipam.example.com/api/v1/api-tokens \
  -H "Authorization: Bearer <jwt-or-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"monitoring","expires_in_days":180,"scopes":["read"]}'

{
  "id": "3f1c...", "name": "monitoring",
  "token": "jt_prod_XXXXXXXXXXXXXXXXXXXX",
  "token_prefix": "jt_prod_", "expires_at": "2027-01-26T00:00:00Z",
  "scopes": ["read"]
}

2通用慣例Conventions

• 基底路徑：/api/v1。所有請求與回應都是 JSON（Content-Type: application/json），除少數明講的 CSV 端點。 Base path: /api/v1. Requests and responses are JSON (Content-Type: application/json), apart from a few explicitly-CSV endpoints.
• 識別碼是 UUID，不是遞增整數。 Identifiers are UUIDs, not incrementing integers.
• 時間一律 ISO 8601、UTC（2026-07-30T12:34:56Z）。 Timestamps are ISO 8601 in UTC (2026-07-30T12:34:56Z).
• 未知欄位會被拒絕。寫入用的 schema 是嚴格模式（extra=forbid）—— 多送一個拼錯的欄位會回 422，而不是安靜忽略。 Unknown fields are rejected. Write schemas are strict (extra=forbid) — a misspelled extra field returns 422 instead of being silently ignored.
• 部分更新用 PATCH，只送要改的欄位。 Use PATCH for partial updates, sending only the fields you want to change.

分頁Pagination

列表端點吃 page（從 1 起算）與 page_size，回應固定是這個外層： List endpoints take page (1-based) and page_size, and always return this envelope:

{ "items": [ … ], "total": 1234, "page": 1, "page_size": 50 }

page_size 上限視端點而定（多數是 200）。要抓完整資料就依 total 逐頁取。 The page_size cap depends on the endpoint (usually 200). To fetch everything, page through using total.

3錯誤與狀態碼Errors & status codes

錯誤回應一律是 {"detail": "…"}；422 另外附 errors 陣列指出哪個欄位不合法。伺服器端不會回 stack trace。 Errors are always {"detail": "…"}; 422 additionally carries an errors array pinpointing the invalid fields. Stack traces are never returned.

{ "detail": "Invalid request",
  "errors": [ { "loc": ["body","cidr"], "msg": "value is not a valid IPv4 network", "type": "value_error" } ] }

4權限模型Permission model

jt-ipam 是預設關閉（deny by default）。你的權杖看得到什麼，完全取決於擁有者被授權了什麼： jt-ipam is deny by default. What your token can see depends entirely on what its owner has been granted:

• 可逐物件授權的資料（區段／子網路／IP／裝置／機櫃／地點／客戶）→ 只回你可見範圍內的，連 total、統計與趨勢都會跟著縮放。 Per-object data (sections / subnets / IPs / devices / racks / locations / customers) → only what you can see, and total, counts and trends scale with it.
• 全域基礎設施資料（VLAN／VRF／NAT／防火牆／DNS／虛擬化／佈線／電力…）→ 需要「全域讀取」（admin 或萬用讀取授權）。只被指派特定物件的帳號會拿到 403。 Global infrastructure (VLAN / VRF / NAT / firewalls / DNS / virtualization / cabling / power…) → requires global read (admin or a wildcard read grant). Accounts scoped to specific objects get 403.
• 純管理資料（稽核記錄、使用者／群組／權限、系統與整合設定）→ 需要 admin。 Administrative data (audit log, users / groups / permissions, system and integration settings) → requires admin.

想知道自己這把權杖有什麼能力，打 GET /api/v1/me：回應含 is_admin、has_visibility、has_global_read。 To discover what your token can do, call GET /api/v1/me: the response includes is_admin, has_visibility and has_global_read.

5區段（Sections）Sections

最上層的分組容器，子網路掛在區段底下。可有父子階層。 The top-level grouping container that subnets belong to. Supports parent/child nesting.

建立區段Create a section

curl -X POST https://ipam.example.com/api/v1/sections \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Taipei DC","description":"main site"}'

6子網路（Subnets）Subnets

curl -X POST https://ipam.example.com/api/v1/subnets \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"cidr":"192.0.2.0/24","section_id":"<section-uuid>","description":"office LAN"}'

7IP 位址（Addresses）IP addresses

查詢參數Query parameters

# 查某網段裡所有 IP
curl -G https://ipam.example.com/api/v1/addresses \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "subnet_id=<subnet-uuid>" --data-urlencode "page_size=200"

# 依主機名稱找
curl -G https://ipam.example.com/api/v1/addresses \
  -H "Authorization: Bearer $TOKEN" --data-urlencode "q=web01"

8裝置（Devices）Devices

9搜尋與 IP 工具Search & IP tools

GET /api/v1/search?q=…&limit_per_type=… 是全域搜尋，跨區段／子網路／IP／裝置／客戶等型別，並依你的可見範圍過濾。支援部分 MAC 首碼（如 bc:24）。 GET /api/v1/search?q=…&limit_per_type=… searches across sections, subnets, IPs, devices, customers and more, filtered to what you may see. Partial MAC prefixes (e.g. bc:24) work.

/api/v1/tools/* 是一組無副作用的計算端點，適合腳本直接呼叫： /api/v1/tools/* is a set of side-effect-free calculators handy for scripts:

10完整資源索引Full resource index

API 共約 500 條路由。上面詳述的是最常用的核心資源；其餘資源大多遵循同一套 GET 列表 ／ GET {id} ／ POST ／ PATCH ／ DELETE 慣例。 The API has roughly 500 routes. The sections above cover the core resources in detail; most others follow the same GET list / GET {id} / POST / PATCH / DELETE convention.

11phpIPAM 相容 API-compatible API

給既有的 phpIPAM 腳本用的相容層：換掉網址與權杖就能沿用，回應是 phpIPAM 的外層格式。 A compatibility layer for existing phpIPAM scripts: change the URL and token and they keep working, with phpIPAM-shaped response envelopes.

基底路徑：/api/phpipam/<app_id>/。<app_id> 沿用你原本 phpIPAM 的 App ID 字串。 Base path: /api/phpipam/<app_id>/, where <app_id> is whatever App ID string your scripts already use.

認證Authentication

三種標頭都收（挑一個就好）：token: jt_…、phpipam-token: jt_…、Authorization: Bearer jt_…。也可以用帳號密碼走 Basic Auth 換一把 30 天的權杖： Any one of three headers works: token: jt_…, phpipam-token: jt_…, or Authorization: Bearer jt_…. You can also exchange username/password over Basic Auth for a 30-day token:

curl -X POST -u 'user:password' \
  https://ipam.example.com/api/phpipam/myapp/user/

{ "code":200, "success":true, "data":{ "token":"jt_prod_…", "expires":"…" }, "time":0.01 }

12Graylog DSV 查表 lookups

給 Graylog 的「DSV File from HTTP」配接器用的免登入唯讀端點，回 CSV。認證是一把系統層級的權杖，走網址參數 ?token=（由 admin 在「管理 → Graylog DSV」產生），因為 Graylog 抓檔時不能帶自訂標頭。 Unauthenticated, read-only CSV endpoints for Graylog's "DSV File from HTTP" adapter. They are gated by a system-level token passed as ?token= (generated under Admin → Graylog DSV), because Graylog cannot send custom headers when fetching.

curl "https://ipam.example.com/api/v1/lookup/hostnames?token=<dsv-token>"

"192.0.2.10","web01"
"192.0.2.11","db01"

在 Graylog 的 DSV 配接器裡，Key column = 0、Value column = 1（欄位索引從 0 起算）。防火牆相關端點要先在該台整合設定裡勾選「提供防火牆 DSV」才會有資料。 In Graylog's DSV adapter set Key column = 0 and Value column = 1 (indices are 0-based). The firewall endpoints only return data once "expose firewall DSV" is enabled on that instance.

13MCP（給 LLM 用） (for LLMs)

jt-ipam 內建 MCP（Model Context Protocol）伺服器，讓 LLM 用自然語言查 IPAM。走 JSON-RPC 2.0： jt-ipam ships an MCP (Model Context Protocol) server so an LLM can query the IPAM in natural language, over JSON-RPC 2.0:

• Streamable HTTP：POST /api/mcp。initialize 的回應會帶 Mcp-Session-Id 標頭。支援 initialize、ping、tools/list、tools/call。 Streamable HTTP: POST /api/mcp. The initialize response carries an Mcp-Session-Id header. Supports initialize, ping, tools/list and tools/call.
• stdio（本機用，例如 Claude Desktop）：python -m app.mcp.stdio_server，權杖放環境變數 JT_IPAM_MCP_TOKEN。 stdio (local, e.g. Claude Desktop): python -m app.mcp.stdio_server, with the token in JT_IPAM_MCP_TOKEN.

認證用 X-Auth-Token 或 Authorization: Bearer，可以是： Authentication uses X-Auth-Token or Authorization: Bearer, with either:

• 對外唯讀 MCP 金鑰（jtmcp_…，admin 在「管理 → LLM／AI」產生並輪替）—— 只看得到唯讀工具，異動類工具會被隱藏並擋下。要先啟用「對外 MCP」才會生效。 A read-only external MCP key (jtmcp_…, generated and rotated by an admin under Admin → LLM/AI) — read-only tools only; mutating tools are hidden and blocked. External MCP must be enabled first.
• 一般 API 權杖（jt_…）—— 依該權杖擁有者的權限。若這把權杖是唯讀 scope，MCP 同樣只給唯讀工具。 A regular API token (jt_…) — scoped to its owner's permissions. If the token is read-only, MCP likewise exposes only read-only tools.

curl -X POST https://ipam.example.com/api/mcp \
  -H "X-Auth-Token: jtmcp_xxxxxxxx" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

14代理協定Agent protocols

掃描代理與憑證派送代理有自己的通道，用各自獨立的金鑰（X-Agent-Key 標頭，建立代理時產生、只存雜湊），不是 API 權杖。這些端點是給代理程式用的，一般整合不需要碰。 The scan agent and certificate-distribution agent have their own channel, authenticated by per-agent keys (the X-Agent-Key header, issued when the agent is created and stored only as a hash) rather than API tokens. These endpoints are for the agents themselves; normal integrations don't need them.

bundle/raw?part=pkcs12 可帶 X-Pfx-Password 標頭。帶了就回以該密碼加密、且 Windows 匯得進去的 PKCS#12（PBESv1-SHA1-3DES）—— PBESv1 是 Windows CryptoAPI 全版本都吃的形式；函式庫預設的 PBESv2/AES-256 失敗時訊息是誤導的「密碼不正確」。不帶標頭時行為不變（不加密）。Windows 代理每次執行自產一組隨機密碼且只留在記憶體，私鑰不會為了匯入而寫到磁碟。 bundle/raw?part=pkcs12 accepts an X-Pfx-Password header. With it you get a PKCS#12 encrypted with that password using the encryption Windows can actually import (PBESv1-SHA1-3DES) — PBESv1 is the form every version of the Windows CryptoAPI accepts; the library default, PBESv2/AES-256, fails with a misleading "the password is incorrect". Without the header the behaviour is unchanged (unencrypted). The Windows agent generates a random password per run and keeps it in memory, so the private key is never written to disk on the way in.

另有兩支完全免認證的健康檢查端點，給負載平衡器用：GET /healthz（存活）與 GET /readyz（就緒，DB／Redis 不通時回 503）。 Two entirely unauthenticated health endpoints exist for load balancers: GET /healthz (liveness) and GET /readyz (readiness, returning 503 when the DB or Redis is unreachable).

15速率限制與 CORSRate limits & CORS

依來源 IP 分桶限流，超過回 429 並帶 Retry-After（秒）。預設值（可在後端設定調整）： Rate limits are bucketed per source IP; exceeding one returns 429 with Retry-After (seconds). Defaults (configurable in the backend):

CORS：正式環境只允許明確列出的 HTTPS 來源（不接受 *、不接受 HTTP）。因此瀏覽器端的跨網域呼叫預設不會通 —— 第三方整合請走伺服器對伺服器。 CORS: in production only explicitly-listed HTTPS origins are allowed (no *, no HTTP). So cross-origin browser calls will not work by default — do third-party integrations server-to-server.

16OpenAPI

後端是 FastAPI，會自動產生 OpenAPI 規格。但正式環境（APP_ENV=production）一律關閉 /docs、/redoc 與 /openapi.json，避免對外洩漏完整攻擊面。 The backend is FastAPI and generates an OpenAPI spec automatically. However /docs, /redoc and /openapi.json are disabled in production (APP_ENV=production) so the full attack surface isn't published.

要拿完整的機器可讀規格（含每個端點的全部欄位），在非正式環境的實例上開一台即可： To get the complete machine-readable spec (every field of every endpoint), run a non-production instance:

APP_ENV=development uvicorn app.main:app
curl http://127.0.0.1:8000/openapi.json > jt-ipam-openapi.json

拿到 openapi.json 之後可以直接餵給 openapi-generator 產出各語言的 client。 Feed that openapi.json to openapi-generator to produce a client in your language of choice.