Interact with TP-Link Omada SDN Controller Open API. Use when querying or managing Omada network devices, clients, sites, access points, switches, gateways, VLANs, firewall rules, VPNs, or any Omada controller configuration. Also use when the user mentions Omada, SDN controller, or needs to authenti

Omada SDN Controller API Manage TP Link Omada SDN Controllers via the Open API (OpenAPI 3.0.1). Compatibility The Open API is available in Omada SDN Controller v5.9 and later (both the Software Controller and Cloud Based Controller). Earlier versions only have an undocumented internal API that uses cookie based session auth — this skill does not cover that legacy API. The Open API feature must be explicitly enabled by an administrator before use. Environment Setup Before making any API calls, you need three environment variables. If the user has not provided these or a .env file does not exist, walk them through the setup: 1. Find the controller URL — Ask the user for their Omada Controller address. This is typically https://<host :8043 for the Software Controller. The port may differ if customized during installation. 2. Create API credentials — Guide the user to: Log into the Omada Controller web UI Navigate to Global View Settings Platform Integration Open API Click Add New App Set the type to Client (not Gateway) Copy the generated Client ID and Client Secret 3. Create the .env file — Have the user create a .env file in the project root: Never commit .env to git. Ensure .gitignore includes it. Load variables before making requests: Do NOT use source .env — variables won't propagate to subshells or curl. If auth fails, common causes are: The Open API feature is not enabled on the controller The client app type is set to Gateway instead of Client The controller URL is wrong or missing the port The client secret was rotated in the UI but not updated in .env Locating the Wrapper Script The API wrapper script is at scripts/omada api.sh relative to this skill's directory. On first use in a session, find the script path using Glob to search for /omada controller/scripts/omada api.sh . Use the discovered absolute path for all subsequent calls. For example, if the skill is installed at .claude/skills/omada controller/ , the script path is .claude/skills/omada controller/scripts/omada api.sh . Making API Calls Always use the wrapper script for all Omada API calls. It handles env loading, authentication, and URL construction automatically. Anti patterns: Any command beyond bash <script ... triggers extra permission prompts. NEVER pipe, chain, or post process script output with other commands. Use jq FILTER for filtering and read the JSON output yourself for anything else. NEVER use curl, prefix assignments, or shell variables. Common anti patterns: bash <script ... jq ... — use jq FILTER flag instead bash <script ... python3 c "..." — use jq or read the output yourself cat saved response.txt python3 c "..." — read the JSON yourself, do not shell out curl sk "${OMADA URL}/api/info" — use the script, not curl SITE="123" && bash <script ... — inline the value directly in the path SITE="123"; for mac in ... — no shell variables or loops On first use in a session , run the health check with no arguments. This verifies connectivity and lets the user approve the script once for all subsequent calls: Then make API calls: The path is relative to /openapi/v1/{omadacId} — no need to construct full URLs or manage tokens. Examples Path Routing The script routes paths automatically: /sites/... → /openapi/v1/{omadacId}/sites/... /v2/sites/... → /openapi/v2/{omadacId}/sites/... /v3/api docs → {OMADA URL}/v3/api docs (no auth prefix) Recommended Permission Users should add this to their Claude Code settings to allow the script without repeated prompts: API Discovery The controller hosts its own full OpenAPI 3.0.1 spec (~1,507 endpoints). Use it to discover any endpoint at runtime rather than hard coding paths. Swagger UI (browser): {OMADA URL}/swagger ui/index.html — no auth required OpenAPI spec (JSON): Common Patterns Site ID Most endpoints are site scoped. Get the site ID first: Then use it in subsequent paths: /sites/{siteId}/devices , /sites/{siteId}/clients , etc. Pagination Paginated endpoints accept page and pageSize query parameters and return: API Versions Some endpoints use /v2/ instead of the default /v1/ . The swagger spec includes both — prefix the path with /v2 when needed. Authentication Details The wrapper script handles auth automatically, but for reference: 1. Controller ID : Fetched from GET {OMADA URL}/api/info (outside the OpenAPI spec) 2. Token : OAuth2 client credentials via POST {OMADA URL}/openapi/authorize/token?grant type=client credentials with omadacId , client id , client secret in the JSON body ( grant type is a query param, not body) 3. Header format : Authorization: AccessToken=<token (NOT Bearer ) 4. Expiry : Tokens last 2 hours (7200 seconds) — the script re authenticates each call Gotchas Quoting : Always quote paths containing & (e.g., "/sites?page=1&pageSize=100" ). Unquoted & is a shell background operator. TLS : The controller typically uses a self signed cert. Always use curl k . MAC format : The API uses AA BB CC DD EE FF (uppercase, dashes). Error handling : Always check errorCode in responses. 0 = success, negative = error. Token header : Authorization: AccessToken=<token , NOT Bearer <token . References [scripts/omada api.sh](scripts/omada api.sh) — API wrapper (handles env, auth, and requests) [references/api categories.md](references/api categories.md) — API endpoint categories and counts [references/external resources.md](references/external resources.md) — Links to docs, examples, and integrations

omada-controller